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CHAPTER  1 


INTRODUCTION 


1.  PURPOSE.  SKETCH  is  an  image  understanding  operating  system  designed  for  use 
by  the  serious  programmer  who  is  trying  to  construct  and  debug  complex  A1  Image 
Understanding  programs.  The  emphasis  in  SKETCH  is  on  being  small,  efficient,  and 
flexible,  and  on  promoting  modularity  of  the  final  program.  SKETCH  is  not  intended  to 
be  an  image  processing  system  for  non-programmers. 

SKETCH  is  also  useful,  in  the  hands  of  an  experienced  programmer,  for  evaluating 
the  performance  of  algorithms,  complex  or  simple,  against  large  data  sets,  and  for  storing 
resulting  images  and  tables  on  disk  for  rapid  review  and  reference. 

2.  REQUIREMENTS.  SKETCH  strives  to  meet  the  following  requirements: 

2.1.  SKETCH  IS  LISP  BASED.  An  interpretive  language  is  desirable  for  control, 
because  the  programmer  productivity  of  an  interpretive  language  is  at  least  50%  better 
than  that  of  a  compiled  language. 

Little  use  of  disk  should  be  made  during  the  computation,  for  speed  reasons. 

The  best  standard  language  for  these  purposes  is  LISP. 

2.2.  SKETCH  USES  FORTRAN  AND  C  FOR  SIGNAL  PROCESSING.  No 
LISP,  including  COMMON  LISP  in  most  of  its  current  implementations,  seems  to  be  able 
to  handle  numeric  computations  in  a  cost  effective  manner.  Therefore,  array  oriented 
algorithms  need  to  be  written  in  FORTRAN  or  C. 

2.3.  SKETCH  INTERFACES  WITH  EXISTING  DATA.  Tapes  in  existing  data 
libraries  usually  do  not  have  to  be  reformated. 

2.4.  SKETCH  PROCESSES  MODERATE  AMOUNTS  OF  DATA.  Develop¬ 
ment  of  AI  Image  Understanding  algorithms  requires  testing  against  many  thousands  of 
images.  Although  this  is  usually  not  practical,  because  the  CPU  time  requirements  are 
excessive,  it  is  at  least  practical  to  test  against  hundreds  of  small  images  each  day,  given 
proper  support.  This  involves  batch  runs,  storing  results  on  disk  for  rapid  review  and 
reference,  and  interactively  repeating  alternative  computations  on  any  input  image  that 
requires  further  analysis. 

2.5.  SKETCH  INTERFACES  WITH  EXISTING  AI  PACKAGES.  Existing  AI 
software  packages,  like  OPS5,  PEARL,  etc.,  should  be  integrable  with  SKETCH. 
SKETCH  should  not  prejudge  the  representation  of  symbolic  data,  because  different 
representations  have  different  efficiencies  in  different  applications. 
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2,6.  SKETCH  PROMOTES  MODULARITY.  Users  of  the  SKETCH  should  gen¬ 
erally  be  able  to  write  signal  processing  modules  without  regard  to  interfaces  other  than 
those  defined  by  the  SKETCH. 

3.  MAJOR  SKETCH  COMPONENTS.  SKETCH  supports  several  general  purpose 
object  data  types  that  facilitate  communications  between  user  subroutines  in  the  same 
way  that  the  floating  point  number  types  do:  by  providing  easy  to  use  standards  that 
everyone  can  use  without  much  thought.  Specifically  provided  are  SKETCH  array,  cata¬ 
log,  and  display  data  types,  and  extra  support  for  the  LISP  S-expression  data  type  when 
it  is  used  for  messages  to  human  users.  SKETCH  also  provides  an  object  package  with 
specific  support  for  defining  semantic  networks  and  storing  them  in  catalogs  (i.e.,  files). 

3.1.  THE  ARRAY  PACKAGE-  SKETCH  tries  to  do  for  array  computations  what 
the  floating  point  number  did  for  simple  arithmetic:  provide  a  single  array  data  type 
everyone  can  share,  and  reduce  user  bookkeeping  operations  to  a  minimum. 

SKETCH  arrays  support  element  values  not  supported  in  other  systems.  Block 
floating  point  elements  are  supported:  that  is,  elements  that  are  stored  as  integers,  with 
all  elements  of  the  same  array  being  multiplied  by  the  same  power  of  two.  Block  floating 
point  arrays  are  useful  to  compact  array  storage  on  disk  or  in  MOS  memory,  and  have 
been  useful  in  the  past  to  speed  computation  on  computers  with  slow  floating  point 
hardware.  Missing  values  are  also  supported  for  array  elements,  even  in  block  floating 
point  and  on  computers  without  IEEE  floating  point. 

More  precisely,  SKETCH  supports  arrays  with  8-,  16-,  and  32-  bit  signed  or 
unsigned  block  floating  point  numbers,  1-bit  unsigned  integers,  and  32-  or  64-  bit  floating 
point  numbers.  Any  array  with  signed  numeric  values  may  store  missing  values. 

SKETCH  allows  a  subroutine  that  has  received  an  array  to  request  that  the  array  be 
put  in  the  format  of  the  subroutine’s  choice.  The  subroutine  can  ask  for  the  array  to 
have  single  precision  floating  point  elements,  for  example,  and  if  the  array  does  not 
already  have  these,  it  will  be  converted  to  have  them.  In  image  processing  work,  it  is  also 
often  desirable  to  add  extra  rows  and  columns  around  the  edges  of  a  2D  array  by  mirror¬ 
ing  the  rows  and  columns  near  the  edges,  and  this  can  be  requested  by  the  subroutine  at 
the  same  time. 

Thus  the  programmer  is  relieved  from  the  burden  of  having  to  present  arrays  in  the 
right  format  to  each  subroutine.  There  is  no  debilitating  speed  penalty  for  conversion  of 
array  element  types  and  provision  of  boundary  extension  values,  as  this  is  accomplished 
by  working  with  data  in  blocks,  rather  than  one  element  at  a  time. 

Similarly,  because  arrays  are  allocated  in  a  garbage  collected  memory,  the  program¬ 
mer  is  relieved  from  managing  memory,  or  allocating  output  arrays  for  a  subroutine  he  is 
calling.  Each  subroutine  merely  allocates  its  own  output  arrays  with  the  element  format 
it  prefers,  and  returns  these  arrays  as  values  to  its  caller. 

In  SKETCH,  arrays  are  not  just  collections  of  elements,  but  are  in  fact  a  vector  of 
elements  plus  a  linear  map  of  array  subscripts  to  vector  subscripts.  Two  arrays  may 
share  the  same  vector,  and  as  any  linear  subscript  map  is  allowed,  one  array  may  be  a 
window  into  the  other,  or  a  transpose  of  the  other. 

SKETCH  also  solves  the  problem  of  writing  functions  that  deal  with  arrays  of  any 
dimension;  for  example,  elementwise  addition  of  arrays  of  any  dimension.  SKETCH 
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makes  all  arrays  6  dimensional,  with  unused  dimensions  set  to  size  1.  An  elementwise 
array  addition  program  checks  all  its  arrays  for  identical  dimension  sizes,  and  then  exe¬ 
cutes  6  nested  loops,  with  the  outermost  loops  iterating  only  once  for  unused  dimensions. 
The  6  nested  loops  are  embedded  in  a  macro,  so  the  fact  that  there  are  as  many  as  6  loops 
is  generally  invisible  to  the  programmer. 

SKETCH  arrays  have  several  facilities  aiding  input/output.  First,. the  array  control 
information  is  stored  separately  from  the  array  elements  on  disk.  The  control  informa¬ 
tion  is  stored  as  ASCII  LISP  S-expressions,  human  readable  and  editable,  in  files  called 
catalogs  (catalogs  are  discussed  in  more  detail  below).  The  array  elements  are  stored  in 
binary  form,  in  separate  files  called  array  caches,  and  are  pointed  to  by  the  control  infor¬ 
mation,  which  contains  the  file  name  and  offset  of  where  the  elements  are  stored. 

As  a  consequence  of  this  arrangement,  array  control  information  may  be  copied 
between  catalog  files  without  copying  the  binary  elements.  Different  catalogs  may  be 
created  without  duplicating  array  elements. 

Arrays  have  a  property  list  like  LISP  symbols,  permitting  the  user  to  add 
identification  and  other  information  to  arrays.  This  information  is  stored  with  the  array 
control  information  in  catalogs,  and  may  be  used  to  select  arrays  from  a  catalog. 

When  an  array,  i  e.,  its  control  information,  is  read  from  a  catalog,  the  array  in 
MOS  memory  has  no  elements,  but  continues  to  point  at  the  elements  on  disk.  If  the  ele¬ 
ments  of  an  array  are  wanted  in  a  particular  format  by  some  subroutine,  and  the  ele¬ 
ments  are  not  in  MOS  memory  but  are  on  disk,  then  the  elements  are  read  from  disk. 
Before  altering  elements  of  an  array,  a  program  indicates  that  it  wants  to  write  the 
array,  and  the  array  is  marked  ais  no  longer  having  valid  elements  on  disk.  But  if  the 
array  elements  are  not  altered,  the  array  continues  to  remember  where  its  elements  are 
stored  on  disk. 

When  an  array  is  written  into  a  catalog  file,  the  array  elements  will  be  written  into 
an  appropriate  array  cache  file,  if  an  only  if  these  elements  do  not  already  exist  some¬ 
where  on  disk. 

Thus  catalogs  containing  arrays  can  be  copied  and  edited  without  copying  array  ele¬ 
ments  unnecessarily. 

A  general  underlying  idea  of  SKETCH  is  that  the  elements  of  an  array  can  be  in 
many  different  formats  in  many  different  places.  SKETCH,  as  it  now  exists,  makes  less 
use  of  this  notion  than  it  might,  but  uses  it  enough  to  work  well.  Future  versions 
designed  for  parallel  computers  would  necessarily  make  extensive  use  of  the  notion, 
because  in  addition  to  changing  the  element  format  of  an  array,  and  adding  mirrored 
edges  to  image  arrays,  different  subroutines  would  also  want  arrays  to  be  laid  out  in 
different  ways  in  parallel  memory. 

3.2.  THE  OBJECT  PACKAGE.  The  object  package  is  used  to  store  information 
about  arrays  and  other  objects.  It  combines  significant  features  of  the  LISP  defstruct 
facility,  LISP  property  lists,  and  objects  in  the  SMALLTALK  language.  Objects  are  LISP 
values  which  have  a  type  and  attributes.  The  attributes  play  the  role  of  properties  in  a 
property  list,  defstruct  slots,  or  SMALLTALK  messages. 

The  storage  of  objects  and  access  to  their  attributes  can  be  optimized  after  the 
manner  of  defstruct.  The  method  for  doing  this  is  extensible,  and  the  SKETCH  object 
system  should  be  integrable  with  the  data  storage  systems  of  other  AI  tools,  e  g.  PEARL. 
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Currently  the  SKETCH  object  package  is  well  integrated  vviili  the  C  language  structure 
defining  facility. 

An  important  feature  of  SKETCH  is  that  attribute  labels  and  object  types  do  not 
have  to  be  predeclared,  nor  is  it  necessary  to  specify  in  advance  all  the  attributes  that  can 
be  attached  to  a  SKETCH  object  or  all  the  types  of  SKETCH  objects.  Input  data  can 
create  attribute  labels  and  object  types  on  the  fly,  as  can  interpreted  code.  With  special 
syntax,  compiled  code  can  do  this  too.  In  this  respect,  SKETCH  objects  are  similar  to 
LISP  property  lists.  The  SKETCH  data  cataloging  facility  makes  important  use  of  this 
feature. 

It  is  possible  to  have  access  to  an  attribute  of  a  SKETCH  object  trigger  a  function, 
and  to  pass  extra  arguments  to  that  function.  By  this  means  the  basic  capabilities  of 
SMALLTALK  objects  are  supported.  Operations  not  having  to  do  with  attribute  access 
can  also  be  defined  on  objects.  These  are  generic  in  that  they  have  different  definitions 
when  applied  to  different  object  types. 

The  SKETCH  objects  package  permits  both  a  function  and  a  macro  to  be  supplied 
for  operations  on  objects  and  attributes.  The  macro  is  used  to  obtain  efficiency  when 
there  is  sufficient  information  about  object  types  available  at  macro  expansion  time.  The 
function  performs  the  operation  when  such  information  is  not  available  until  later. 

The  SKETCH  objects  package  also  facilitates  I/O  of  recursive  semantic  networks  by 
providing  a  system  for  naming  objects  with  analogs  of  symbol  print  names,  and  a  system 
for  forward  referencing  named  objects  pointed  at  by  other  objects  being  read  into 
memory.  In  a  catalog  a  reference  to  a  named  object  is  represented  by  just  the  type  and 
name  of  the  object.  When  a  forward  reference  to  an  object  is  read,  a  place  holder,  or 
stub,  is  allocated  for  the  object.  Later,  when  the  full  object  is  read,  the  stub  is  filled  in 
with  the  rest  of  the  object  attributes. 

3.3.  THE  CATALOG  PACKAGE.  The  catalog  package  stores  information  in  the 
file  system  concerning  arrays  and  other  LISP  values.  A  catalog  is  just  a  sequence  of 
objects  stored  in  an  ASCII  file. 

Catalog  entries  are  LISP  values  that  are  read  and  evaluated  to  create  objects. 
Because  they  are  evaluated,  they  can  represent  objects  by  giving  algorithms  for  comput¬ 
ing  them,  rather  than  just  by  providing  a  direct  representation  of  the  object. 

To  write  an  object  in  a  catalog,  one  unevaluates  the  object  and  prints  the  resulting 
expression.  Unevaluation  is  a  standard  objects  package  operation  that  can  be  defined 
according  to  object  type.  The  unevaluate-print-read-evaluate  mechanism  of  data  storage 
and  retrieval  is  a  very  powerful  mechanism  for  representing  complex  objects  in  catalogs. 

Catalogs  can  include  other  catalogs.  A  special  include  entry  can  be  placed  in  one 
catalog  to  cause  the  contents  of  a  second  catalog  to  appear  to  replace  the  include  entry  in 
the  first  catalog. 

Catalogs  can  be  defined  as  applying  filters  to  other  catalogs.  A  filter  is  a  function  of 
one  variable.  If  one  catalog  is  a  filter  of  a  second  catalog  by  a  particular  function,  the 
function  is  applied  to  each  object  in  the  second  catalog  to  make  the  corresponding  object 
of  the  first  catalog.  This  is  done  incrementally  whenever  an  object  is  to  be  read  from  the 
first  catalog.  By  returning  the  special  value  please-ignore,  the  function  can  cause  objects 
from  the  second  catalog  to  be  deleted,  in  the  sense  they  will  be  skipped  when  objects  are 
read  from  the  first  catalog. 
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An  index  for  a  catalog  may  be  built  and  saved  on  disk,  so  random  access  in  the  cata¬ 
log  is  fast. 

It  is  generally  easy  to  write  programs  which  read  existing  datasets  and  produce 
SKETCH  catalogs  listing  the  arrays  in  these  datasets.  These  cataloged  array  objects  can 
contain  whatever  parameters  describe  the  data.  In  particular,  they  may  include  new 
attributes  not  declared  to  SKETCH  code. 

3.4.  THE  DISPLAY  PACKAGE.  The  display  package  implements  display  objects 
and  the  means  of  displaying  them  on  a  monitor.  Display  objects  are  basically  memories 
that  describe  2D  arrays  of  pixels.  Included  is  an  intensity  array  which  typically  has  one 
8- bit  unsigned  integer  code  per  pixel.  Display  objects  reference  color  maps  that  map  pixel 
intensity  codes  to  colors.  Display  objects  can  additionally  have  up  to  32  bitgraph  planes, 
each  with  one  bit  per  pixel.  Pixels  with  a  ‘T  bit  in  a  bitgraph  plane  are  overlaid  with  a 
color  code  determined  by  the  plane.  Each  bitgraph  plane  is  individually  erasable,  permit¬ 
ting  somewhat  dynamic  displays. 

Bitgraph  planes  are  used  to  store  text  and  vectors.  A  display  can  also  store  text  and 
vectors  in  an  S-expression  based  format  that  can  be  used  to  redraw  this  portion  of  the 
display  in  a  different  resolution. 

The  display  package  emphasizes  display  device  independence  and  the  pre- 
computation  of  displays  for  rapid  browsing.  Display  objects  can  be  stored  in  catalogs, 
after  the  manner  of  any  SKETCH  object  some  of  whose  attributes  are  SKETCH  arrays 

3.5.  THE  TOP  LEVEL  PACKAGE  (TO  BE  IMPLEMENTED).  The  top  level 
package  will  contain  functions  commonly  used  to  control  SKETCH  runs.  Computations 
of  objects  from  other  objects  are  defined  by  tables  so  that  when  an  object  is  required  it 
can  be  computed  in  the  most  efficient  possible  manner.  Information  about  generating 
displays  is  similarly  defined  by  tables.  Given  these  tables,  a  user  can  quickly  customize 
interactive  jobs  that  compute  and  display  objects,  and  batch  jobs  that  precompute 
objects  and  displays  for  later  use.  The  user  can  also  quickly  modify  the  form  of  the 
display  and  the  objects  displayed. 

Detailed  CPU  timing  statistics  will  also  be  automatically  recorded. 

Currently  the  top  level  package  does  not  exist. 

4.  MANUAL  CONVENTIONS.  SKETCH  is  a  set  of  packages,  each  of  which  is 
documented  in  its  own  manual  chapter  (or  appendix).  The  last  section  of  a  package 
chapter  is  the  GLOSSARY,  which  describes  all  the  global  names  defined  in  the  package. 
Also  described  are  a  few  technical  terms  used  in  the  package  documentation.  Names 
defined  in  the  glossary  are  italicized  wherever  they  appear  in  the  manual.  There  is  an 
index  of  all  glossary  names  in  Appendix  A. 

The  sections  of  the  package  chapter  before  the  GLOSSARY  are  called  the  tutorial 
for  the  package.  The  glossaries  by  themselves  are  complete  reference  documentation:  the 
package  tutorials  are  not  generally  complete.  If  there  is  no  tutorial,  it  is  recommended 
that  one  first  read  the  demonstration  program  listings  for  the  package  that  appear  after 
the  manual,  looking  up  the  new  names  encountered  in  the  glossary  as  you  go. 

Just  before  a  package  glossary  there  is  often  a  section  titled  HITLIST  which  lists 
known  problems  with  the  package  which  we  would  like  to  fix,  plus  enhancements  we 
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might  like  to  make. 

See  APPENDIX  D  for  more  details  on  writing  package  chapters. 

5.  GETTING  STARTED.  To  get  started  invoke  the  sketch  program  as  a  UNIX  com¬ 
mand.  This  program  is  in  the  SKETCH  root  directory  (you  must  ask  where  this  root 
directory  is  on  your  system).  It  is  a  lisp  environment  with  all  the  features  of  the  FRANZ 
/i5p(l)  program,  plus  the  additional  features  of  SKETCH.  For  example,  if  you  invoke 
sketch  and  at  the  prompt  *— >’  you  type— 

(prm^array  [an-array  has-sizes  *(10  10)  by •  expression  '{sum  X  Y))) 

then  SKETCH  will  print  out  a  10X10  array  with  each  element  equal  to  the  sum  of  the 
subscripts  that  reference  the  element, 

SKETCH  should  be  learned  by  trying  things  out  as  you  read  the  manual.  In  lieu  of 
this,  you  may  consult  the  demonstration  listings  at  the  end  of  the  manual.  Demonstra¬ 
tion  programs  are  run  as  if  they  had  been  typed  into  sketchy  one  line  at  a  time,  and  the 
resulting  display  was  made  into  a  listing.  Such  demonstration  programs  are  used  to 
debug  programs  initially,  to  recheck  programs  after  changes,  and  to  act  as  examples  for 
new  users.  Demonstration  programs  with  names  of  the  form  xxx_xdemo.l  may  be  found 
in  package  subdirectories  of  the  SKETCH  root  directory. 

The  SKETCH  compiler,  named  sketchcom,  is  used  just  like  FRANZ  //.^r/(l). 
Skelchcom  is  also  in  the  SKETCH  root  directory, 

SKETCH  C  code  can  be  compiled  with  the  normal  C  compiler,  provided  you 
^include  the  appropriate  package  Ji  files.  These  are  in  the  package  subdirectories  of  the 
SKETCH  root  directory,  and  you  should  compile  with  UNIX  commands  such  ns¬ 
ec  -0  -c  -/<SKETCH-root-directory >  <filel>.c  ... 
which  permit  the  SKETCH  .h  files  to  be  found. 

Each  package  has  a  file  named  <xxx/xxx_defs.h>  relative  to  the  SKETCH  root 
directory.  This  .h  file  includes  everything  that  C  language  code  needs  to  use  the  package. 
Here  xxx  is  the  package  prefix,  the  same  prefix  as  on  all  global  names  defined  by  the  pack¬ 
age.  E.g.,  if  you  use  5ar_array,  defined  by  the  ARRAYS  package,  ^include 
<sar/sar^dejs,h> , 

The  ARRAYS  package  .h  file,  <sar/sar^defs.h> ,  includes  the  .h  files  of  all  packages 
appearing  before  it  in  this  manual.  Since  most  programs  do  not  use  C  global  names  that 
are  defined  in  packages  after  the  ARRAYS  package  in  this  manual,  one  can  often  just 
include  this  ARRAYS  package  .h  file  and  nothing  else. 

There  is  also  a  sophisticated  and  fairly  easy  to  use  SKETCH  file-making  facility 
built  on  top  of  the  UNIX  make  program.  See  APPENDIX  C  for  details. 
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FRANZ  EXTENSIONS 


1.  FRANZ  EXTENSIONS.  This  package  consists  of  a  set  of  miscellaneous  functions 
that  extend  the  capabilities  of  FRANZ  LISP  in  many  different  directions.  Tables  on  this 
and  the  following  pages  briefly  describe  the  functions  and  global  variables  defined  by  this 
package.  All  these  are  defined  in  more  detail  in  the  glossary,  but  those  marked  w  ith  a 
dagger  (j)  are  also  mentioned  in  the  tutorial  sections  before  the  glossary. 

2.  PRETTY  PRINTING.  The  philosophy  of  SKETCH  is  that  messages  intended  for 
people  can  be  organized  as  LISP  lists.  The  messages  are  usually  like  sentences  with  the 
left  parenthesis  serving  in  place  of  initial  capitalization  and  the  right  parenthesis 
serving  as  the  period.  Paragraphs  are  just  lists  of  sentences,  with  an  extra  **(’  serv  ing 
paragraph  beginning  and  an  extra  as  paragraph  end. 

The  pretly-print  function  prints  arbitrarily  complex  lists,  and  is  the  heart  of  the  svs> 
tern  for  outputting  messages  Unlike  most  other  programming  languJge^,  this  sy^^tem 
does  formatting  almost  automatically,  relieving  the  programmer  of  a  very  siibstnntini 


ARITHMETIC 

(ceiling  ‘n^number) 

Computes  the  smallest  integer  that  is  not  less  than 
n number. 

(floor  ’n^number) 

Computes  the  largest  integer  that  is  not  larger  than 
n^number. 

p» 

sqrt-pi 

The  constant  pi  and  its  square  root. 

(round  ^n_number) 

Computes  the  nearest  integer  to  a  given  number. 

ENVIRONMENT 

^is-compiler”^ 

Non-nj7  in  a  SKETCH  compiler  environment,  and  nil  in  a 
SKETCH  evaluator  environment. 

SFE_LINT  t 

C  Macro.  1  if  macro  expansion  is  being  done  for  lint,  0  if 
for  the  C  compiler. 

SFE.VAX 

C  Macro.  1  if  compilation  is  for  a  DEC  VAX.  0  if  not. 

SFE_MC68000 

C  Macro.  1  if  compilation  is  for  a  Motorola  6S000.  0  if  not. 
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ERROR  CHECKING  AND  HANDLING 


(assert  *g_condition  [’g^message]) 

LISP  macro.  Evaluates  g^condition,  and  if 
it  is  nil,  calls  error  with  g message. 

(ccheck  ’g^value)  f 

A  LISP  function  to  check  w  hether  a  C  func¬ 
tion  that  has  just  been  called  has  signaled  an 
error  by  calling  sfe^error.  If  yes,  reads  the 
error  message  stored  by  sfe^error  and  passes 
it  to  error.  If  no  returns  g value. 

(error  M_message)  f 

Signals  that  an  error  has  occurrecL  taking  as 
a  single  argument  an  error  message, 
Lmessage,  which  is  a  list  to  be  pretty- 
print' eA. 

(error-trace  ’s_switch) 

Sets  a  switch  that  if  on  causes  the  system  to 
continuously  keep  records  that  allow  the  de¬ 
tailed  state  of  the  stack  to  be  printed  if  an 
error  should  occur.  Unfortunately,  this 
record  keeping  can  be  quite  consumptive  of 
CPU  cycles. 

*exit-on-error* 

If  non-m7,  causes  the  program  to  exit  on  an 
error. 

sfe_assert  (g_test,  t_message)  f 
sfe_assertl  (g_test,  t^message, 
sfe_assert2  (g_test,  t_message,  ...) 
sfe_assert3  (g«test,  t^message,  ...) 
sfe_assert4  (g_test,  t_message,  ...) 
sfe assert5  (g test,  t^message,  ...) 

A  C  Macro.  Evaluates  g_test,  and  if  false 
(0),  calls  sfe_error  with  t_message  and  the 
other  arguments  (...)  to  signal  the  error,  and 
then  calls  sfe^retnrn  to  take  an  error  return 
from  the  current  C  function. 

sfe_check  ()  f 

A  C  macro.  Checks  whether  a  C  function 
just  called  signaled  an  error  by  calling 
sfe^error.  If  yes,  calls  sfe^return  to  take  an 
error  return  from  the  current  C  function. 

sfe_error  (t^message,  ...)  f 

A  C  function.  Called  with  a  message  to  sig¬ 
nal  an  error.  T_message  and  the  other  argu¬ 
ments  (...)  are  as  for  sprinif.  Sets  an  error 
switch  that  is  read  and  reset  by  ccheck,  and 
stores  the  error  message  in  a  buffer  for 
ccheck  to  read  and  pass  to  error. 

sfe_iserror  ()  f 

A  C  macro  that  returns  true  (non-zero)  if 
the  error  switch  set  by  sfe^error  is  on. 

sfe_return;  t 

A  C  macro.  Returns  from  the  current  C 
function.  For  use  if  an  error  has  occurred. 
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FILE  HANDLING 

(demo  ’s_input-file  [t] 

[’s_output-file  [<]]) 

Reads  from  s_input-file  and  produces  output  as  if 
the  lines  of  s_input-file  were  typed  in.  The  output 
may  be  redirected  to  s output-file. 

(search- path  ’(s_directory  ...) 

’s_file  (’s_mode]) 

Searches  for  and  returns  the  full  pathname  of  a  file 
given  a  list  of  directories,  the  user  supplied  partial 
pathname  s_file,  and  an  access  mode,  s_mode,  which 
is  V,  ’u;,  or  ’a  to  denote  read,  write,  or  append. 

(split-filenaine  ’aL-filename) 

Separates  the  directory  part  of  s_filename  from  the 
basename  part,  returning  the  two  element  list: 
fdirectory-name  base-name). 

(stringopen  ’t_string  ’x_size  f 
’s_mode  [’t_name]) 

Opens  a  port  that  makes  t_string  into  a  file.  X_size 
is  the  number  of  bytes  in  t_string,  and  s_mode  is  V, 
t_3tring  are  not  treated  specially,  and  Vs,  'ws,  or  'as 
for  read,  write,  or  append  where  NUL’s  are  specially 
treated  as  the  end-of-file. 

(use-ptport  ’p_port) 

Indicates  when  output  sent  to  p_port  is  also  being 
sent  to  ptport.  Useful  for  making  C  code  that  uses 
priiuf  work  right  with  demo. 

LIST  HANDLING 

(copy-list  MJist 

(’xjength  ’g_fill]) 

Copies  IJist,  without  recursively  copying  sublists 
(unlike  copy).  Can  optionally  fill  the  resulting  list 
to  a  specific  xjength  with  elements  equal  to  g_fill, 
or  truncate  the  result  to  xjength. 

(equal-filled-Iists 

’l_list-l  ’l_list-2  ’g_fill) 

Tests  equality  of  lists,  filling  the  shorter  list  with 
elements  equal  to  g_fill,  if  the  lists  are  not  of  equal 
length. 

(list-depth  ’g^value) 

Computes  the  nesting  depth  of  sublists  of  g_value 
Returns  0  if  g value  is  not  a  list. 

(list-length  ’gjist 

[’u_predicate]) 

Computes  the  length  of  gJist,  verifies  that  the  list 
terminates  with  a  ni7,  and  can  optionally  check 
whether  the  list  elements  satisfy  u_predicate.  Re¬ 
turns  the  list  length  if  all  is  well,  or  -1  otherwise. 
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LOADING  AND  DUMPING 

(cload  ’([s_discipline]  s_function  ...)  f 
’(s_file  |s_library])) 

Loads  G  language  s_file.o  file  containing 
definitions  of  s_function  ...  with  calling  dis¬ 
cipline  s_discipline.  S_library  specifies  C  .0 
file  libraries  to  be  searched  after  loading 
s file.o. 

(dumplisp  s_file)  t 

Dumps  the  current  evaluator  or  compiler  en¬ 
vironment  into  a  file,  s_file,  which  becomes  a 
new  evaluator  or  compiler. 

MEMORY  MANAGEMENT 

(car ray  ’a_array) 

Returns  address  of  first  element  of  a_arrny  as  a 
fixnitm.  so  that  can  be  passed  to  a  C  function. 

*gc-history* 

*gc-history-count* 

*gc-count* 

Variables  that  hold  records  of  garbage  collector  ac¬ 
tivity. 

(purearray  ...) 

(^purearray  ...) 

Like  the  LISP  array  macro  or  *arr(ii/  function,  but 
allocates  an  array  whose  elements  are  ignored  by 
the  garbage  collector.  This  speeds  up  garbage  col¬ 
lection. 

(puresegment  's_type  ’x^ize) 

Returns  the  first  of  x_size  contiguous  LISP  objects 
of  typep  type  s_type.  Like  segment,  but  the  allocat¬ 
ed  elements  are  ignored  by  the  garbage  collector. 
This  speeds  up  garbage  collection. 
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MEMORY  REFERENCE 

(copy-setf-function  ^s_symbol 

^s source) 

Makes  s_symbol  have  the  same  se// behavior 
as  s source. 

(defsetf  s function  ...) 

Defines  the  se// behavior  of  s function. 

(dpb  ’x_value  #oPPSS  ’x_number) 

Returns  x_number  with  the  field  specified  by 
#oPPSS  (see  Idb  below)  replaced  by  x value. 

(has-setf-function  ’s_symbol) 

Returns  non-/M7  if  s_symbol  has  a  seif 
behavior. 

(Idb  #oPPSS  ’x_number) 

Returns  the  bit  field  obtained  by  right  shift¬ 
ing  x_number  by  PP  bits  and  masking  off 
the  low  order  SS  bits.  PP  and  SS  are  octal 
numbers. 

(vrefi-double  ’V_vector  \\_index) 

Accesses  the  x^index-hTst  Jionuin  stored  in 
the  immediate  vector  V vector. 

(vsiie-long  ’V_vector) 
(vsize-double  V_vector) 

Returns  the  number  of  3*2  bit  long  fixnum's 
or  64  bit  double  Jlomnn's  stored  in  the  im¬ 
mediate  vector.  V_vector. 
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PRINTING  AND  PRETTY  PRINTING 

float- for  mat 

The  C  format  in  which  LISP  flonum's  are 
printed.  Defaults  to  "%.6g"  in  SI^TCH. 

*  line- length* 

The  line  length  in  columns  for  pretty  print¬ 
ing.  Defaults  to  80. 

(pretty-format  ’g_value 
[’xjevel]) 

Returns  the  format  of  g_value  for  pretty 
printing.  Such  a  format  gives  detailed  in¬ 
structions  for  controlling  optional  carriage 
return  insertion. 

(pretty-print  ’g_value  t 
[’p_port 
[’x_margin 
[’s_string 
[’x_repeat 

(’x right-margin||Ijl) 

Prints  g_value  in  a  pretty  format  by  insert¬ 
ing  carriage  returns  and  tabs.  In  detail,  first 
prelfy-JormaVs  the  value  and  then  pretty- 
prinl-JorinaVs  the  resulting  format. 

(pretty-print- format 
’g-format 
[’p^port 
(’x_margin 
[’s^tring 
(’x_repeat 

Px right-margin)!lll) 

Pretty  prints  a  format,  g_format,  returned 
by  pretty-format. 

(pretty-tab  ’x_margin 
[’p_port 
[’s_string 
(’x repeatlin 

Tabs  to  the  x_margin’f Tst  column.  Permits 
special  line  headers  to  indicate  indentation 
of  tracing  or  similar  matters. 

(print-size  ’g_value 

|’x_maximuml) 

Computes  the  number  of  characters  that 
would  be  outputted  by  print'lng  g_value. 
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TIMING 

(fdelay  T_time) 

Delays  until  f_time.  F^tinne  is  iis  nneasiired 
by  ftime. 

(ftime) 

Returns  a  finely  measured  time-  The  error 
of  measurement  is  1/60'th  second  or  less. 
The  time  returned  is  measured  in  seconds 
from  midnight,  Jan.  1,  1970.  GMT. 

*ptime-counts-per-second* 

The  number  of  ticks  per  second  for  the  value 
returned  by  the  ptime  function. 

(xtime  ’g_expression) 

Measures  the  CPU  time  in  seconds  taken  by 
the  evaluation  of  g_expression,  exclusive  of 
garbage  collection  time. 
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TOP  LEVEL 

(argv-shift  [’x_number]) 

Removes  x^number  arguments  from  the  be¬ 
ginning  of  the  list  of  UNIX  command  line  ar¬ 
guments  which  are  individually  returnable 
by  arqv. 

*top-level-init* 

*  top-level-exit* 
*top-Ievel-prompt* 

*  top- level- read  * 
*top-Ievel-eval* 

*  top- level-print* 

*  top-  level-times  * 

*top- level-print-times* 

Global  variables  which  are  set  to  the  func¬ 
tions  that  perform  various  parts  of  the  top 
level  algorithm.  May  be  reset  to  control 
that  algorithm. 

*top-level-init-started* 

*top-level-init-times* 

*top-level-saved-times* 

*top-level-saved-print-times* 

Global  variables  used  by  the  top  level  to 
save  information. 

(status  top-level-rc-files)  f 

The  list  of  places  to  look  for  a  parameter  file 
to  be  read  during  initialization  of  a 
SKETCH  evaluator  or  compiler. 

(status  top-level-switches)  j 

The  list  of  switches  {-E  and  -/)  that  will  be 
recognized  and  processed  at  the  beginning  of 
the  UNIX  argument  list  to  a  SKETCH 
evaluator  or  compiler. 

*top-level-threshold-time*  f 

The  minimum  time  in  seconds  that  must  be 
consumed  by  evaluating  an  expression  read 
by  the  top  level  before  timing  statistics  for 
evaluating  the  expression  will  be  printed  out. 

+  t 
++t 
+++ 1 

The  last  (-f),  next-to-last  (-f-f),  and  next-to- 
next-to-last  (4H-+)  expression  read  by  the 
top  level. 

♦  ♦♦  ^ 

The  last  (*),  next-to-last  (**),  and  next-to- 
next-to-last  (***)  result  of  evaluating  an  ex¬ 
pression  read  by  the  top  level. 

burden.  Also,  SKETCH  pretty-print  is  somewhat  more  sophisticated  than  most  other 
LISP  pretty  printers. 

As  an  example,  consider  the  LISP  expression— 

{pretty-print  ‘(cannot  open  ,file  for  writing)) 

which  is  intended  to  output  an  error  message  in  the  case  a  file  cannot  be  opened  for  out¬ 
put.  There  is  no  need  for  the  programmer  to  worry  about  line  feeds  in  long  error  mes¬ 
sages,  such  as  when  the  file  has  a  very  long  name.  The  pretty-print  function  will  insert 
line  feeds  for  him.  However,  the  programmer  must  put  line  feeds  after  messages,  using 
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the  terpri  function,  as  pretty-print  does  not  do  this. 

The  normal  FRANZ  LISP  error  function,  which  signals  that  an  error  has  occurred 
and  outputs  an  error  message^  has  been  modified  to  take  a  single  list  argument  as  the 
error  message  which  is  to  be  pretty  printed.  E.g.— 

[error  ‘(cannot  open  .file  for  writing)) 

Although  LISP  does  have  formatted  print  routines  similar  to  those  of  C  and  FOR¬ 
TRAN,  their  use  is  avoided  in  SKETCH,  because  they  do  not  automatically  insert  car¬ 
riage  returns  or  indent  for  readability. 

3.  RC  FILES.  Whenever  any  version  of  a  SKETCH  evaluator  or  of  a  SKETCH  com¬ 
piler  is  loaded,  it  searches  for  files  in  the  list  returned  by  — 

[status  top’levet’rc-files) 

and  applies  the  LISP  load  function  to  the  first  such  file  found.  The  usual  default  values 
for  these  lists  are— 

[sketch.rc  .. /sketch. rc  /sketch. rc  \'sketch.rc) 

for  the  SKETCH  evaluator  and— 

[sketchcom.rc  ../sketcliconi.rc  ../../  sketclicoin  rc  ' /sketch com.  rc) 
for  the  SKETCH  compiler. 

4.  SKETCH  SWITCHES.  When  a  SKETCH  evaluator  or  compiler  is  loaded,  and 
after  any  top-level-rc-files  are  loaded,  the  following  argument  flags  are  processed.  .\n\ 

-/  file-name 

arguments  cause  the  file-name  to  be  loaded  by  the  LISP  load  function.  .\ny 

-£*  "expression" 

arguments  cause  the  expression  to  be  read  by  the  LISP  read  function  and  evaluated  by 
the  LISP  eval  function.  Any  errors  occurring  during  these  loadings  and  evaluations  will 
terminate  the  SKETCH  program.  The  arguments  so  processed  must  be  at  the  beginning 
of  the  argument  list,  and  will  be  removed  from  the  argument  list.  The  rest  of  the  argu¬ 
ment  list  may  then  be  accessed  as  if  these  removed  arguments  had  never  e.xisted. 

5.  TOP  LEVEL  VARIABLES.  The  top  level  reads  an  input  expression,  evaluates  it, 
and  prints  the  resulting  value.  The  global  variables  -h,  ++,  and  -I— I— I-  are  set  respectively 
to  the  last,  next-to-last,  and  next-tonext-to-last  expressions  read.  The  global  variables  *, 

and  ***  are  set  respectively  to  the  results  of  evaluating  the  last,  next-to-last,  and 
next-to-next-to-last  expressions  read. 

If  evaluation  of  an  expression  takes  more  than  ^top-level-threshold-time*  seconds 
(including  time  for  garbage  collections),  then  after  the  evaluation  result  is  printed,  a  mes¬ 
sage  indicating  how  long  evaluation  took  and  how  much  of  that  time  was  spent  garbage 
collecting  is  printed.  In  the  message  the  phrase  compute-time  refers  to  CPU  time  not 
spent  garbage  collecting,  while  the  phrase  gc-time  refers  to  CPU  time  spent  running  the 
normal  FRANZ  LISP  garbage  collector.  *top-level-threshold-time*  to  1  second 
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6.  STRING  FILES.  SKETCH  supports  the  use  of  character  strings  in  memory  as 
files.  This  permits  output  to  be  prepared  for  displays  without  having  to  first  write  the 
output  on  disk.  It  is  also  used  for  passing  error  mes.sages  from  C  to  LISP.  This  facility  is 
implemented  by  the  5/nngopen  function  described  in  the  glossary. 

7.  DUMPLISP.  The  FRANZ  LISP  dumplisp  function  has  been  extended  so  that  it  will 
correctly  dump  a  SKETCH  evaluator  or  compiler  environment.  The  resulting  file  can  be 
executed  as  a  new  variant  of  the  sketch  evaluator  or  compiler. 

When  a  SKETCH  compiler  is  called  without  arguments  (other  than  — E  or  — /),  it 
will  read  and  evaluate  its  standard  input,  just  like  any  LISP  environment.  Statements  in 
this  input  may  load  files  and  then  call  dumplisp. 

8.  LOADING  C  AND  FORTRAN  FILES.  Loading  C  and  FORTRA.N  .o  files 
should  be  done  with  the  cloud  function,  which  is  described  in  the  glossary.  This  function 
allows  C  and  FORTRAN  .o  files  to  be  reloaded  into  the  current  LISP  environment.  It 
does  this  by  taking  as  an  argument  a  list  of  all  the  global  function  names  and  initialized 
variables  in  the  .o  file,  and  removing  these  from  the  symbol  table  before  reloading  the  file. 

To  fully  understand  argument  passing,  it  is  necessary  to  read  the  section  on  foreign 
functions  in  the  FRANZ  LISP  manual  chapter  on  functions.  However,  the  following  will 
suffice  for  many  purposes.  Numeric  arguments  and  values  will  be  appropriately  passed 
without  problems.  Functions  with  the  c-/w;?ci/o7i  discipline  return  integers  which  become 
LISP  fixnum^s,  and  functions  with  the  double- c- function  discipline  return  floating  point 
numbers  that  become  LISP  flonxnn's.  Lists,  symbols,  character  strings,  hunks,  and  vec¬ 
tors  may  be  passed  as  arguments,  and  will  be  passed  as  pointers  ecpial  to  their  respective 
addresses.  Except  for  character  strings,  these  are  all  structures  defined  in  the  SKETCH 
ATOMS  package. 

(C  functions  that  return  LISP  values  are  currently  difficult  to  write  because  FRANZ 
lacks  a  discipline  for  them.  This  should  be  fixed.] 

9.  PASSING  ERROR  MESSAGES  FROM  C  TO  LISP.  The  sfe^error  function 
can  be  called  from  C  to  record  an  error  message  and  set  an  error  switch.  This  function 
takes  the  same  arguments  as  print/.  The  message  is  written  into  a  string  file  (see  above), 
and  is  later  read  by  the  LISP  read  function  and  passed  to  the  LISP  error  function.  Thus 
the  message  must  be  a  valid  representation  of  a  LISP  value.  An  example  is- 

5/c_error  ("(cannot  open  %s  for  writing)”, 
sat^sformat  (file^name)); 

where  the  sat^sformat  function  from  the  ATOMS  package  reformats  the  character  string 
file^name,  if  necessary,  so  that  it  is  a  valid  LISP  symbol  (e.g.  #play  becomes  l#play|). 

Upon  returning  to  LISP  from  C  the  error  switch  is  checked  by  the  cclieck  function. 
If  set,  it  is  cleared,  the  error  message  is  read  using  rend,  and  the  error  function  is  called 
with  the  LISP  value  read.  The  form  for  employing  cclieck  is  usually 

(cc/iec/:  (_some_C_function  ...)) 

in  which  ccheck,  if  it  finds  the  error  switch  off,  returns  the  value  of  its  argument,  w  hich  is 
the  value  returned  by  _some_C_f unction. 

There  are  a  variety  of  C  utility  functions  for  working  with  the  error  handling  facil¬ 
ity  just  described.  The  sfe^assert  macro  makes  a  test  and  calls  sfe^error  if  the  test  fails. 
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Eg- 

sfe^asseri  (coxnii  >  0,  ** (count  argument  is  •C=  Of): 

In  the  failure  case,  sfe^assert  also  returns  from  the  current  function.  It  does  this  by  e.xe- 
cuting  the  sfe^return  macro,  which  defaults  to  return  (0),  but.  which  can  be  redefined  by 
the  programmer  if  it  is  necessary  for  the  current  C  function  to  clean  up  on  an  error 
return,  or  if  0  is  incompatible  with  the  data  type  of  the  value  returned  by  the  function. 
Sfe^assert  is  heavily  used  to  test  for  errors  in  C  functions. 

It  is  moderately  rare  for  SKETCH  C  functions  to  call  each  other.  When  they  do, 
the  caller  may  have  to  check  the  error  switch  upon  return  from  the  called  function.  This 
is  done  with  the  sfe^iserror  macro.  The  sje^check  macro  combines  this  test  with  an  call 
to  sfe_return  if  the  error  switch  is  on.  E  g.— 


my_function  (...); 
sje^check{)\ 


10.  DEFINING  FUNCTIONS  AND  GLOBAL  VARIABLES  FOR  LINT.  It  is 
important  to  lint  C  functions  to  find  errors.  When  doing  so,  all  functions  callable  in  C 
code  outside  the  file  in  which  they  are  defined  should  be  given  public  definitions  sufficient 
to  specify  the  types  of  their  arguments.  This  is  done  by  including  code  such  as- 

a^ij  SFE^LINT 

#ijndej  PPP3[MMM_C 
/*  ARGSUSED  7 
somejunction  (argument_l,  ...) 

type_l  argument_l;  ...  {  re/urns(0);  } 

^  endif 

#  endif 

in  the  ./i  file  of  the  package  that  defines  the  function.  The  statement 

^define  PPP_MMM^LC 

must  also  be  included  before  any  ^inc/ude  statements  in  the  file  ppp_mmmm.c  that  gives 
the  normal  definition  of  the  function. 

This  code  works  as  follows.  If  a  file  other  than  ppp_mmmm.c  is  being  linted, 
SFE^INT  will  be  1  and  PPP_MMMM_C  will  be  undefined.  Therefore,  the  definition  of 
somej'unction  given  in  the  .h  file  will  actually  be  used  by  lint.  If  ppp_mmmm.c  is  being 
linted,  this  definition  will  be  suppressed  by  the  #i/nde/ PPP3'IMMM_C.  If  a  file  is  being 
compiled  instead  of  linted,  this  definition  will  be  suppressed  because  SFE^LINT  will  be  0. 

The  function  definition  accessed  by  lint  needs  to  declare  the  type  of  each  argument 
and  the  type  of  the  value  returned.  The  body  of  this  function  definition  should  consist 
only  of  a  valid  return  statement  if  the  function  returns  a  value.  If  the  function  returns  no 
value,  the  body  should  be  empty.  The  special  line- 

/*  ARGSUSED  y 

must  be  placed  before  this  function  definition  to  keep  lint  from  complaining  that  the 
arguments  are  not  used  in  the  function  body. 

A  similar  thing  must  be  done  for  global  variables.  To  keep  lint  happy,  these  must 
be  given  an  e.xplicit  extern  in  the  normal  part  of  the  Ji  file,  and  then  redefined  without  the 
extern  inside  ff^ij  SFE^LINT  and  #jynde/PPP_MMMM_C. 
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11.  HITLIST 

(1)  Provide  library  directories  and  searching  for  autoload. 

Make  cload  handle  composite  files  consisting  of  many  .o  files  linked  together.  These 
will  load  faster  in  nu/o/oad  situations. 

(2)  Add  general-c-fu notion  discipline  to  return  lisp  values  from  C  functions. 

(3)  Speed  up  pretty-print. 

(4)  Possibly  add  argument  processing  facility. 

(5)  Possibly  add  new  reader/printer  that  uses  expression  syntax  and  operator  hierarchy. 

(6)  Add  abbreviation  handler. 

(7)  Make  error  set  prinkngth  and  prmlevel  to  reasonable  values. 

12.  GLOSSARY. 

(argv-shift  [^'.number])  [LISP  Function] 

SIDE  EFFECT:  Remove  x^number  arguments  from  the  beginning  of  the  command  line 
arguments  returnable  by  argr.  Specifically,  remove  the  arguments 
returned  by  (nr^i;  1)  through  (ar(7v  x_number).  (or^vO)  is  left  untouched. 
X_number  defaults  to  1. 

(assert  ’g_condition  [’g_message|)  [LISP  Macro] 

SIDE  EFFECT:  Evaluates  g_condition,  and  if  false  evaluates  (error  g_message). 

G_message  defaults  to  ’(g_condition  is  false).  Note  that  g_message  is 
evaluated  only  if  given  and  g_coiidition  is  false. 

(carray  ’a_array)  [LISP  Macro] 

RETURNS:  An  integer  equal  to  the  address  of  the  first  data  word  of  the  array.  This  can 
be  passed  to  a  c-function  as  the  address  of  the  beginning  of  the  array. 

(ccheck  *g_value)  [LISP  Function] 

WHERE:  ’g_value  is  usually  a  call  to  a  C  or  FORTRAN  function  loaded  by  cload:  e.g.,  as 
in- 


[ccheck  (_sar_copy  x  y)) 

RETURNS:  G_value. 

SIDE  EFFECT:  A  check  is  made  to  see  if  a  C  function  has  called  sfe_error  since  the  last 
call  to  ccheck.  If  the  answer  is  yes,  error  is  called  with  the  LISP  expres¬ 
sion  read  from  the  character  string  generated  by  the  call  to  sfe^error. 
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(ceiling  n_iuiniber)  jLlSP  Function' 

RETURNS:  The  smallest  integer  greater  than  or  equal  to  n«number. 

(check-list  ’gjist  [’u.predicatej)  [LISP  Function] 

RETirRNS:  -1  if  g_list  is  not  a  normal  niT-terminated  list  each  element  of  which  satisfies 
u_predicate,  if  that  is  given.  Otherwise  returns  the  number  of  elements  m 
gjist  (0,  1;  ...). 

(cload  ’([s_discipline]  s_function  ...)  [LISP  Functionl 

’s.file) 

(cload  ’([s_discipline|  sjunction  ...)  [LISP  Function] 

’(s_file  [sjibrary])) 

WHERE:  S_file.o  (s_file  ^Yith  the  extension  ,o  added)  is  an  object  file  of  some  foreign 
language,  most  likely  C  but  maybe  FORTRAN  or  PASCAL.  This  file  is 
assumed  to  contain  the  functions  with  global  load  names  s_function  ....  In 
order  to  allow  reloading  of  this  file,  these  global  names  should  be  an  exhaustive 
list  of  all  global  functions  defined  in  the  file.  Note  that  if  the  names  are  those 
of  C  global  functions,  they  must  being  with  as  the  load  names  of  all  global  C 
functions  have  _  prefi.xed  by  the  C  compiler. 

S_discipline  is  one  of  the  FRANZ  function  disciplines  or  the  symbol  co//x/n///. 
which  refers  to  initialized  global  data.  The  default  is  c-function,  which  refers  to 
a  C  language  function  that  returns  an  integer.  Some  other  possibilities  are 
(louble-c-Jfinctioji  which  is  a  C  function  returning  a  real  number,  li6p-c-fu7iction 
which  is  a  C  function  returning  a  lisp  value,  integer-ftincitoii  which  is  a  FOR¬ 
TRAN  function  returning  an  integer,  and  real-function  which  is  a  FORTR.\N 
function  returning  a  real.  See  the  FRANZ  LISP  documentation  on  functions 
for  other  disciplines  and  a  precise  explanation  of  the  calling  linkages. 

The  first  argument  is  a  list  of  s^discipline’s  and  s_function’s,  with  each 
s^discipline  applying  to  all  the  functions  following  it  and  an  implicit  c-function 
at  the  beginning  of  the  list.  No  function  name  may  be  the  same  as  a  discipline. 
The  possible  disciplines  are  listed  in  the  global  constant  *Junc lion- disciplines^ 

SJibrary  is  passed  as  a  character  string  to  the  UNIX  loader  (Id)  as  the  library 
to  be  searched  for  undefined  globals.  It  may  also  be  a  list  of  more  than  one 
library:  e.g. 

^1-lm  -IV  foo.aj. 

SIDE  EFFECT:  Loads  s_file.o,  searching  the  directories  in  the  list  {status  load- search-path) 
just  as  the  load  function  does.  Defines  the  function  definitions  of 
s_function  ...  to  refer  to  the  entry  points  of  the  same  names  in  the  files. 

Does  nothing  if  the  file  is  already  loaded  (this  cload  has  already  been  exe¬ 
cuted,  and  the  file  found  by  searching  directories  does  not  have  a  more 
recent  modification  time  than  the  version  of  the  file  that  was  previously 
loaded. 
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BUG:  If  a  C  or  FORTRAN  function  is  referred  lo  by  other  C  or  FORTRAN  functions, 
then  reloading  the  first  function  will  leave  these  other  C  or  FORTRAN  functions 
referring  to  the  old  version  of  the  function,  and  not  the  newly  reloaded  version. 
This  can  be  corrected  only  by  subsequently  reloading  all  the  functions  that  refer  to 
the  reloaded  function. 

NOTE:  You  should  not  use  initialized  global  variables  in  your  programs,  as  it  is  impossi¬ 
ble  to  reload  the  files  containing  them.  One  can  get  out  of  this  problem  partially 
by  listing  the  global  variable  name  in  the  chad  function  call  as  if  it  were  the 
name  of  a  function.  But  then  one  has  the  problem  that  functions  loaded  before 
the  global  variable  was  reloaded  will  still  refer  to  the  old  global  variable,  and  not 
the  newly  reloaded  one.  This  is  OK  only  if  the  global  variable  is  really  a  con¬ 
stant.  Such  a  variable  should  be  given  the  discipline  covstant. 


‘^compiler^’  [SKETCH  Term] 

MEL'VNS:  A  SKETCH  environment  built  on  top  of  the  liszt  program  which  compiles 
SKETCH  code,  but  does  not  have  all  the  apparatus  to  evaluate  arbitrary 
SKETCH  functions.  A  compiler  is  as  opposed  to  an  evaluator. 

*computer-format*  [LISP  Global  Constant] 

V.aLUE:  The  type  of  the  computer,  from  the  point  of  view  of  the  data  formats  it  uses. 

Thus  all  DEC  vax’s  have  the  type  dec,  all  Motorola  GSOOO’s  have  the  type 
motorola,  most  all  IBM  computers  have  the  type  ibm,  and  most  all  INTEL  com¬ 
puters  have  the  type  iiitel.  Note  that  ibni  and  motorola  use  the  same  integer 
formats  but  different  floating  point  formats.  Ditto  for  dec  and  intel.  Note  that 
all  computers  use  the  same  formats  for  arrays  with  l-bit  or  8-bit  elements  (this 
format  is  determined  by  10  devices,  and  is  IBM  compatible). 

(copy-list  MJist  pxjength  *g_fill])  [LISP  Function] 

RETURNS:  A  copy  of  Llist.  Only  the  top  level  list  cells  are  copied,  unlike  the  copy  func¬ 
tion  (which  copies  list  cells  recursively).  If  the  last  element  of  IJist  is  dotted, 
so  is  the  last  element  of  the  returned  value.  If  xjength  is  given,  the  result 
will  have  exactly  xjength  list  cells.  If  Llist  is  too  short  for  this,  cells  con¬ 
taining  g_fill  will  be  added  (and  the  result  will  be  dotted  if  Llist  is).  If  Llist 
is  too  long,  it  will  be  truncated  (and  will  not  be  dotted  even  if  Llist  is). 

(copy-setf-function  *s_symbol  *s_;50urce)  [LISP  Function] 

EQUIVALENT  TO:  {defsetf  s^ymbol  ...)  where  ...  was  whatever  appeared  in  a  previous 
{defsetf  s_^o\irce  ...).  If  s^ource  has  no  current  setf  expansion  func¬ 
tion,  s_symbol  will  be  set  to  have  no  setf  expansion  function. 
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(copy-string  ’t_5tring)  [LISP  Function] 

RETURNS;  A  copy  of  t_string  that  does  not  share  memory  with  t_string  or  any  other 
string. 

(defcache  s_function  (g_size  s_equal  s_cache)  Largument.s  [LISP  Macro) 

.  Lbody) 

WHERE:  G^ize  defaults  to  10,  s_equal  to  eq,  and  s_cache  to  *s^funct\on-C(ich€*. 

SIDE  EFFECT:  Defines  s_function  after  the  manner  of  defnn  to  be  a  function  that  looks 
items  up  in  a  cache  and  maps  them  onto  values.  The  first  argument  to 
sjunction  is  the  item  to  be  looked  up,  and  the  function  returns  the  value 
found. 

The  cache  is  maintained  in  the  global  variable  s^cache,  which  is  declared 
after  the  manner  of  defvar.  The  size  of  the  cache,  the  number  of  items 
remembered,  is  g_size.  The  most  recently  used  g_size  item/value  pairs 
are  retained  in  the  cache,  and  the  other  items  are  discarded.  The  function 
used  to  test  for  equality  between  items  is  s_equal. 

If  the  item  is  not  found  in  the  cache,  its  value  is  computed  by  the  function 
body,  Lbody,  whose  last  expression  produces  the  value.  The  new 
item/value  pair  is  added  to  the  cache.  L_argumeiits  is  a  normal  defun 
argument  list  for  the  function,  and  arguments  other  than  the  first  may  be 
used  by  the  function  body  to  compute  the  value. 

(defsetf  s_function  (s^expression  s_value)  [LISP  Macro] 

g_statement  ...) 

SIDE  EFFECT:  Defines  a  lambda  function  like  defun  with  two  arguments  named 
s^expression  and  s^value,  and  with  a  body  g_statement  ....  However,  this 
lambda  function  is  not  named  s_function,  but  is  rather  attached  to  the 
property  list  of  s^function  in  such  a  way  that  whenever  the  seif  macro  is 
called  by  an  expression  of  the  form  — 

(5C^/(s_function  ...)  g_value) 
then  the  set/  macro  will  call 

[fxincall  <lambda-function>  ’(s_function  ...)  ’g_value)) 

to  produce  the  macro  expansion  of  self.  Thus  g_statement  ...  should 
return  the  self  expansion  given  that  the  s_expression  argument  is  bound 
to  {s_function  ...)  and  the  s^value  argument  is  bound  to  g_value. 

IXfPLEMENTATION:  FRANZ  actually  implements  this,  but  does  not  document  it. 
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(demo  I’s^input-file  [/j  j’s«output-file  j/j]])  LISP  Function] 

SIDE  EFFECT:  Does  a  read-eval-print  loop  reading  Trom  s_input-file  and  printing  into 
s«outpiit-file.  All  expressions  read  iVom  piporf  are  also  printed,  each  I'ol- 
lowed  by  an  end  of  line.  Atoms  read  by  ratom  and  characters  read  by 
rtadc  or  iyi  are  similarly  printed  (but  not  followed  by  an  end  of  line). 

Prompts  are  printed,  and  in  general  the  behavior  of  the  standard  top  level 
is  faithfully  simulated  with  this  redirected  input  and  output. 

Calls  to  6reoA:  cause  the  equivalent  of  control-D  to  be  typed  and  the  read- 
eval-print  loop  to  be  resumed.  Calls  to  exit  terminate  r/emoonly:  not  the 
program  that  called  demo. 

The  t  switch  following  s_input-file  causes  the  program  to  wait  after  print¬ 
ing  each  prompt  for  a  control-D  to  be  typed  on  the  standard  input.  If  an 
expression  is  typed  instead,  it  is  evaluated  and  printed,  nnother  prompt  is 
typed,  and  the  program  waits  again. 

The  /  switch  following  s_oiitpul-file  causes  output  to  go  into  both 
s_output-file  and  the  standard  output. 

DEFAltLTS:  Output  goes  by  default  to  the  standard  output. 

If  no  arguments  are  given,  those  from  the  last  call  to  demo  are  used. 

NOTE:  While  demo  is  running,  poport,  piport,  and  ptport  are  changed  to  input  from 
s_input-file  and  output  to  the  standard  output  or  s_output-file  as  appropriate. 
Thus  other  functions  can  read  and  print.  Also,  the  read,  ratoni.  readc,  and  fyi 
functions  are  modified  to  print  what  they  read  if  they  read  it  from  piport. 

NOTE:  The  demo  read-eval-print  loop  is  the  same  as  the  SKETCH  top  level  read-eval- 
print  loop,  operating  in  a  slightly  different  mode.  In  particular,  functions  such  as 
*top-level-prompt*^  are  used. 

BUG:  The  characters  read  from  piport  are  not  individually  printed,  but  only  the  results 
returned  by  read.  Thus  comments  are  lost  and  new  lines  are  inserted  after  every 
expression  read,  even  if  this  is  inappropriate.  On  the  other  hand,  if  *top‘level- 
print*  is  a  pretty  printer,  the  print  alignment  of  expressions  read  can  be  much 
improved. 

Similarly  new  lines  and  comments  are  lost  when  using  ratoni. 

BUG:  Uniyi  does  not  work,  and  it  is  suggested  that  tyipeeic  be  used  instead. 

BUG:  Exec  works  and  the  standard  output  from  the  command  it  executes  is  captured  in 
s_output-file,  but  the  standard  error  output  from  the  command  is  not  captured  in 
s_output-file,  and  goes  to  the  standard  error  output  no  matter  what. 

BUG:  If  you  use  the  call— 

(demo  s_input-file  t  ’s_output-file  /) 

and  type  an  expression  in  place  of  "D,  the  expression  will  not  be  printed  in 
s_output-file,  but  the  value  it  evaluates  to  will  be. 
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(dpb  ’x^value  #oPPSS  ^\_number)  [LISP  Function) 

RETURNS:  x_number  with  the  field  specified  by  ^PPSS  (see  Ulb)  replaced  by  \_value. 


(dumplisp  s^file)  [LISP  macro] 

SIDE  EFFECT:  Dumps  the  current  LISP  environment  into  the  file  named  s_file.  Either  an 
evaluator  or  a  compiler  environment  can  be  dumped.  S_file  becomes  a 
program  that  can  be  invoked  as  a  UNIX  command  to  restart  the  environ¬ 
ment. 


(environment  ...) 
(environment-maclisp  ...) 
(environment-lmlisp  ...) 


[LISP  Macro] 
(LISP  Macro] 
^LISP  Macro] 


*in-environment*  LISP  G’lobal  Variable] 

CHANGES:  These  now  maintain  the  global  variable  *in-environwei)t*  which  is  t  when 
load  is  called  by  a  files  clause  in  one  ol*  the  various  encironmenl  statements, 
and  nil  otherwise. 


(equal-filled-Iists  ’Llist-1  'Llist-2  ’g_Rll)  iLlSP  Function) 

RETURNS:  t  if  Llist-1  equals  Llist-2,  and  nil  otherwise.  However,  for  the  purposes  of 
this  comparison,  the  two  lists  are  made  of  e(|ual  length  by  filling  the  shorter 
out  with  elements  equal  to  g_filL  Neither  list  may  be  dotted. 

(error  M_message)  .LISP  Function’ 

(error  ’s/t_message  [’g_data_l  [’g_data_2]])  [LISP  Function] 

EXTENSION  :  May  be  called  with  a  single  argument  which  is  a  list  explaining  the  error 
This  will  be  pretty  printed.  Use  of  this  feature  allows  complex  error  expla¬ 
nations  without  worrying  about  printed  line  lengths. 

SIDE  EFFECT  :  Signals  an  exception,  as  per  the  chapter  on  EXCEPTION  HANDLING  in 
the  Franz  Manual.  The  error  type  will  be  ’ER%err,  the  unique  id  will  be 
1,  and  the  error  will  not  be  continuable.  If  an  errset  is  active,  nil  will  be 
returned  from  the  errset  call. 


If  s/t_message  is  a  string  or  a  symbol,  it  will  become  the  error  message 
string  (it  will  be  made  into  a  symbol  for  that  purpose,  if  it  is  a  string), 
and  g_data_l  and  g_data_2,  if  present,  will  become  the  error  data.  If 
L_message  is  not  a  string  or  symbol,  the  error  message  will  be  ’||  and 
Lmessage  will  become  the  error  data  (in  this  case  g_data_l  and  g_data_2 
may  not  be  given). 

It  is  expected  that  when  printing  an  error  with  error  message  equal  to  '||. 
the  first  and  only  error  datum  will  be  pretty- print’ed,  whereas  when 
printing  any  other  error,  the  error  message  and  all  data  will  be  patom  ed 

BUGS:  More  than  two  error  data  should  be  allowed. 
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(error-trace  *s«switch)  [LISP  Function] 

SIDE  EFFECT:  Turns  error  tracing  on  if  s_s\vitch  is  non- nil,  or  off  if  s_switcli  is  nil.  If  on, 
error  tracing  causes  information  to  be  created  in  the  stack  during  normal 
execution  that  allows  a  detailed  trace  to  be  printed  upon  an  error.  Unfor¬ 
tunately,  creating  this  information  is  costly:  LISP  bound  programs  typi¬ 
cally  run  2.5  times  slower  with  error  tracing  on  than  with  error  tracing 
off.  The  default  is  for  error  tracing  to  be  on. 

IMPLEMENTATION:  Currently  error  tracing  is  implemented  by  {*r$et  and  {sstatus 
translink  nil). 


"‘evaluator”  [SKETCH  Term] 

MEANS:  A  SKETCH  environment  built  on  top  of  the  lisp  program  which  can  evaluate 
any  SKETCH  function  call,  but  does  not  compile  SKETCH  code.  .An  evaluator 
is  as  opposed  to  a  compiler. 

*exit-on-error*  [LISP  Global  ^''ariable| 

VALUE:  If  non-nil  causes  any  error  (routed  trough  ER%tp[)  to  exit  from  the  current  pro¬ 
gram  using  the  value  of  *exit-on-error*  as  the  exit  code.  The  default  value  of 
*  exit- on- err  or*  is  nil,  and  the  recommended  non-ni7  value  is  2. 


(fdelay  T_time)  [LISP  Function] 

SIDE  EFFECT:  Delay  until  Ltime,  which  is  measured  in  seconds  since  00:00.00  GMT,  Jan 
1,  1970.  F_time  may  have  the  same  resolution  as  the  value  returned  by 
/time.  If  the  delay  is  over  a  second,  the  CPU  will  be  given  up  to  other 
users  during  most  of  the  delay. 


(filestat-atime  ...) 
(filestat-ctime  ...) 
(filestat-dev  ...) 
(filestat-gid  ...) 
(filestat-ino  ...) 
(filestat-mode  ...) 
(filestat-mtime  ...) 
(filestat-nlink  ...) 
(filestat-rdev  ...) 
(filestat-size  ...) 
(filestat-type  ...) 
(filestat-uid  ...) 


[LISP  Function 
[LISP  Function 
[LISP  F unction 
[LISP  Function 
[LISP  Function 
[LISP  F  unction 
[LISP  Function 
[LISP  Function 
[LISP  Function 
[LISP  Function 
[LISP  Function 
[LISP  Function 


USE:  Use  these  function  names  instead  of  filestat'.atime  etc.  so  that  code  will  work  in 
those  versions  of  SKETCH  based  on  Franz  LISP  with  packages  (Opus  42  and 
later),  as  well  at  those  without  packages  (Opus  38). 

EQUIVALENT  TO:  The  Franz  Opus  38  functions  filestat'.atime,  etc. 
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float-format  [LISP  Global  N’ariablej 

VALIT:  The  C  language  print/  format  used  by  patom  etc.  to  print  Jloniuns.  Default 
value  is  ”%.16g'*  in  normal  FRANZ  LISP,  but  is  **/o.6g"  in  SKETCH 


(floor  n_number)  [LISP  Function) 

RETURNS:  The  largest  integer  less  than  or  equal  to  n_number. 

(ftime)  [LISP  Function] 

RETURNS:  The  time  in  seconds  since  00:00:00:  GMT.  Jan.  1,  1970,  as  a  jlonuin  with  an 
accuracy  of  at  least  1/60  second. 


gc-history* 

gc- history- length 

gc-count* 

gc-errors* 

gc-dumpfile* 


[LISP  Global  Variable) 
TlSP  Global  \‘‘ariablej 
[LISP  Global  \'ariable] 
[LISP  Global  N’ariable] 
[LISP  Global  Variable] 


VALUE:  *gc-histoTy*  is  a  list  of  messages  summarizing  the  first  *gc-lnstory-length*  gar¬ 
bage  collections  since  the  process  started.  The  default  value  of  *gc~history- 
length  *  is  20. 


*gc‘Count*  is  the  number  of  garbage  collections  since  the  current  j^rocess 
started. 


*gc-errors*  is  the  number  of  garbage  collector  errors  that  have  occurred  since 
the  beginning  of  time  (the  count  is  not  zeroed  by  dinnplisp  and  reload).  After 
the  first  garbage  collection  that  has  errors,  a  dumplisp  is  done  to  the  file  named 
*gc-dumpfHe*  (before  *gc-history*  is  updated).  The  default  value  of  *gc- 
dxtrnpfile*  \s  ^ gc-error-dump. 

NOTE:  The  *gC’history*  messages  are  of  two  types:  compute  messages  specify  am 
amount  of  CPU  time  used  by  non-garbage  collection  computation  between  two 
garbage  collections;  and  gc  messages  specify  an  amount  of  CPU  time  used  by  one 
garbage  collection.  The  messages  are  in  the  order  that  the  actions  occur,  but 
*gc-histoTy*  may  be  slightly  delayed  relative  to  the  current  state  of  the  process 

* 

The  gc  messages  list  the  number  of  pages  allocated  to  each  of  several  types  of 
data:  e.g.  fixnurn^s.  One  of  these  numbers  may  be  of  the  form  N  4*  M:  the  N  is 
the  number  of  pages  that  was  allocated  before  garbage  collection,  and  the  M  is 
the  number  of  fresh  pages  allocated  by  the  garbage  collector  to  try  to  avoid 
another  collection  for  a  while.  The  data  type  for  which  the  number  of  pages  has 
this  N  -f  M  form  is  the  data  type  whose  exhaustion  caused  the  garbage  collection. 
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(gentemp)  [LISP  Function) 

rSE:  Use  gentemp  instead  of  gensym  in  macros,  because  the  latter  will  foul  up  when 
macros  are  expanded  for  execution  at  the  top  level  during  load  in  versions  of  Franz 
that  have  packages. 

The  problem  is  that  gensym  produces  macros  such  as— 

[[lambda  #:g00052)  [suin  #:g00052  5)) 
where  the  two  unintered  generated  symbols  are  not  eg  when  read. 

EQUIVALENT  TO:  [intern  [gensym  'T)).  The  equivalence  is  exact  in  SKETCH  based  on 
Franz  Opus  38,  and  near  in  SKETCH  based  on  Franz  Opus  42  and 
later  Franz’s.  In  the  later  case  see  the  Franz  documentation  for  the 
exact  definition. 

(has-setf-function  ’s^symbol)  [LISP  Function) 

RETURNS:  Non-nil  if  s^ymbol  has  a  self  expansion  function  defined  for  it  by  defsetf 

NOTE:  The  self  expansion  functions  of  some  symbols  are  defined  only  when  they  are 
needed.  E.g.,  caaaar  may  be  so  handled. 

*is-compiler*  [LISP  Global  Variable] 

WALUE;  Non-nil  if  the  current  environment  is  a  compiler,  and  nil  if  the  current  environ¬ 
ment  is  an  evaluator. 

(Idb  #oPPSS  ’x_number)  [LISP  Function] 

RETURNS:  The  bit  field  obtained  by  right  shifting  x_number  by  PP  bits  and  masking  off 
the  low  order  SS  bits.  PP  and  SS  are  octal  numbers. 

(list-depth  ’g^value)  [LISP  Function] 

RETURNS:  The  depth  of  the  list  nesting  in  g_value.  Atoms  (and  hunks)  including  nil 
have  depth  0.  Dotted  lists  are  handled. 

pi  [LISP  Global  Constant] 

sqrt-pi  [LISP  Global  Constant] 

VALUE:  The  indicated  constant  floating  point  number.  Sqrt-pi  is  the  square  root  of  pi. 
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(port-string  ^p.port)  [LISP  Function) 

RETURNS:  The  string  associated  with  p_port  by  siringopen  if  p^port  was  created  l)y 
siringoptn,  or  nil  if  p_port  was  not  created  by  siringopen  and  therefore  has 
no  associated  string.  Note  that  for  the  string  returned  to  be  valid,  a  NUL 
must  have  been  written  at  its  end. 


(pretty- form  at  ’g_value  [’xjevel]) 

*  p  retty- form  at- h  ook  * 

{seif  [get  ’s_symbol  ’pretty-format) 
^character  s_prefix  x_prefix-size)) 
[setf  [get  ’s^ymbol  ’pretty-format) 
’(6rcn/:5  s_brcak  x_count  [*]  ...)) 
prinlevel 
prinlength 


[LISP  Macro] 
[LISP  Global  Variable] 
[LISP  Property] 

[LISP  Property] 

[LISP  Global  Variable] 
[LISP  Global  Variable] 


RETURNS:  The  pretty-print  format  of  g_value.  This  format  contains  a  specification  of 
how  to  print  g_value  that  is  more  precise  than  g_value  itself. 


X^level  is  the  number  of  parentheses  that  will  finally  surround  the  pretty 
printed  version  of  g_value.  If  it  is  equal  to  or  greater  than  prinlevel^  the  ele¬ 
ments  of  a  composite  g_value  should  not  be  printed.  At  most  prinlenglh  ele¬ 
ments  should  be  printed  in  any  case. 

FORMAT  SYNT.\X:  A  pretty  print  format  may  be  a  list  or  an  atom.  If  it  is  an  atom,  it  is 
to  be  print'ed  as  is.  If  it  is  a  list,  then  it  contains  a  list  of  items  which 
are  themselves  pretty-print  formats,  plus  other  information  that  con¬ 
trols  the  insertion  of  carriage  returns  during  the  printing  process. 


The  syntax  of  the  reverse  of  a  pretty  print  format  list  is— 
([x_prefix-size  s_prefix]  [s^break  g_item]  ...  [x_postfix-size  s_postfix]) 

Note  that  for  efficiency  reasons  the  actual  pretty  print  format  is  the 
reverse  of  this  list. 


The  s_prefix  and  s_postfix  are  symbols  that  are  patoin^ed  before  and 
after  the  g^item’s.  For  efficiency  x_prefix-size  and  x_postfix-size  are 
also  given:  these  are  just  the  number  of  characters  that  will  be 
printed  by  patom^ing  s.prefix  and  s_postfix,  respectively.  Either  the 
prefix  information  or  the  p)OStfix  information  may  be  omitted  if  there 
is  no  prefix  or  posfix. 

If  possible  the  prefix,  g_items,  and  s_postfix  will  all  be  printed  on  one 
line,  with  a  single  space  separating  each  pair  of  g_items,  but  no  space 
after  the  prefix  or  before  the  postfix. 

If  everything  will  not  fit  on  one  line,  there  are  several  cases.  In 
describing  these  we  will  refer  to  the  ‘g_item  +  string  following  an 
s_break’.  This  is  the  g_item  following  the  s.break,  plus  any  subse¬ 
quent  pairs  of  the  form  ‘-f- g«item-2’  following  that.  That  is,  the 
longest  following  list  of  gjtem’s  separated  by  s.break’s  that  are  -f. 
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including  these  s^breaks. 

In  the  simplest  case,  the  first  s^break  is  /  or  ^/,  The  item  margin  is 
then  set  to  the  first  column  of  the  printed  prefix,  plus  3  columns.  A 
//  s^break  will  always  return  to  the  item  margin.  A  /  s_break  will 
return  to  the  item  margin  if  necessary  to  avoid  line  overflow  while 
printing  the  following  g_item  -h  string.  A  -{-  s^break  will  return  to 
the  item  margin  plus  3  columns  if  necessary  to  avoid  such  line 
overflow. 

In  the  more  complex  case,  the  first  s^break  is  -h.  The  first  item  will 
then  be  printed  immediately  after  the  prefix,  and  the  item  margin  will 
be  set  to  one  column  after  the  end  of  the  first  item^s  printout.  After 
this  a  -f  s_break  will  return  to  the  item  margin  if  necessary  to  avoid 
line  overflow  while  printing  the  following  g_item  +  string.  When  the 
first  s_break  that  is  not  a  -I-  is  encountered,  a  decision  will  be  made 
about  reseiing  the  item  margin.  If  necessary  to  conserve  horizontal 
space,  the  item  margin  will  be  reset  to  the  starting  column  of  the 
prefix  plus  3  columns,  and  a  carriage  return  will  be  inserted.  After 
this  point,  whether  the  line  margin  is  reset  or  not,  printing  precedes 
as  in  the  simpler  case  above. 

•PRETTY-FORNLA.T-HOOK*:  Pretty-formal  is  a  macro  that  works  by  handling  symbols, 

numbers,  and  strings  inline,  and  executing— 

[Juncall  *pretty-format-liook*  y^value  x^level) 

to  handle  anything  else.  A  series  of  functions  are  be  written 
in  the  form  — 

(rfe/var  *my-format-hook*  {progl  *pretty-format-hook* 

[setq  *pretty-for mat-hook* 
’my-for  mat- hook))) 

{defun  my-format-hook  (the-argument  the-level) 

[or  [progn  ...) 

(funcall  *my-format-hook* 

the-argument  the-level))) 

Each  of  these  functions  processes  the-argument  if  it  is  able  to 
(in  the  progn  block),  and  returns  a  non-nil  format.  Or  the 
function  returns  nil  if  it  is  not  able  to  process  the-argument. 
The  last  function  defined,  the  one  named  in  *pretty-format- 
hook*,  has  the  first  crack  at  the-argument. 

PRETTY-FORMAT  PROPERTY:  If  a  symbol  has  a  pretty-format  property  on  its  property 

list,  the  default  *pretty-fonnat-l\ook*  routine  will  take  spe¬ 
cial  action.  This  property  may  have  one  of  two  forms. 

If  it  has  the  form— 

{character  s«prefi.x  x_prefix-size) 
then  the  symbol  is  like  the  quote  function,  a  function  of 
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one  argumeiU  with  a  special  printed  representation  con¬ 
sisting  of  s.prefix  followed  by  the  argument.  Thus  quoit 
has  the  pretiy-forttiai  property  — 

[character  |’|  l) 

X_prefix-size  is  just  the  print-size  of  s^prefix,  and  is 
included  to  improve  efficiency  by  eliminating  the  recompu¬ 
tation  of  this  size  every  time  it  is  needed. 

If  the  pretty-format  property  has  the  form  — 

(6rea/:s  s_break-l  x_count-l  s_break-2  x_count-2  ...  [*)  ...) 

then  the  symbol  is  treated  as  a  function  of  many  argu¬ 
ments,  like  selq  or  do.  In  the  format  of  a  list  beginning 
with  the  symbol,  the  first  x_count-l  s_break’s  will  equal 
s_break-l,  the  next  x_count-2  s_break’s  will  equal 
s_break-2,  etc.  A  star  (*)  before  an  s_break  indicates  that 
when  the  breaks  list  is  exhausted,  it  is  to  repeat  beginning 
with  the  s_l)reak  just  after  the  star.  For  example,  the 
pretty-format  property  for  set(f  is— 

( breaks  -f  1  *  /  1  -h  l) 

and  for  do  is— 

[breaks  -I-  3  *  /  /  1) 

BUG:  Does  not  handle  strings  or  symbols  containing  embedded  line  feeds  correctly. 

(pretty-print  ’g_value  [’p_port  [’x_margin  [LISP  Function) 

I’s^tring  [’x_repeat  [’x_right_marginj)|]]) 

*line-length*  [LISP  Global  Variable] 

equivalent  TO:  (print  'g_value  [’p_port|)  but  uses  the  line  length  in  the  global  variable 
*line-length*,  and  uses  indentation.  Each  line  begins  with  x^repeat 
s^trings  followed  by  space  till  the  column  equals  x_margin.  At  least 
’x_right-margin  spaces  must  be  left  at  the  end  of  the  last  line  (into 
which  to  put  left  parentheses  for  lists  containing  ’g_value). 

DEFAULTS:  The  default  p_port  is  poport^  the  default  x_margin  is  the  current  column  as 
found  by  nwritn,  the  default  s_string  is  ’||,  the  default  x_repeat  is  1,  and  the 
default  x.right-margin  is  0. 

*  Line- length  *  def^.\\hs  to  76,  which  allows  for  various  things  like  dtf{\)  list¬ 
ings  using  the  first  few  columns  of  a  line,  and  terminals  or  editors  using  or 
abusing  the  last  column. 

NOTE:  If  the  line  is  not  long  enough  to  hold  a  sensible  representation  of  some  part  of 
g_value,  the  indent  may  be  moved  back  to  the  beginning  of  the  line.  The  lines 
where  the  indent  has  been  moved  back  are  bracketed  by  comment  lines  in  the 
form  — 
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;  <<<N 
;  N>>> 

where  N  is  the  current  depth  of  parentheses. 

RETURNS:  Number  of  carriage  returns  printed. 

BUG:  Does  not  handle  strings  or  symbols  containing  embedded  line  feeds  correctly. 

(pretty-print-format  ’gjormat  [’p_port  [\'_margin  [LISP  Function] 

[’s_string  [’x_repeat  [’x_right_margin]|]||) 

EQUIVALENT  TO:  Pretty-print  but  takes  as  input  the  result  g_format  of  applying  pretty- 
format  to  the  item  to  be  pretty-prinfed. 

WARNING:  If  g_format  is  a  list,  it  is  destroyed. 

(pretty-tab  ’x_margin  [’p_port  [’s_string  [LISP  Function] 

l’x_repeat]]]) 

SIDE  EFFECT:  Spaces  until  the  current  column  equals  x_margin.  If  the  current  column  is 
initially  >  x_margin,  a  terpri  is  done  first.  Whenever  spacing  is  begun  at 
the  beginning  of  a  line,  x_repeat  s_string*s  are  printed  before  spacing  is 
done.  The  default  p_port  is  poporl,  the  default  s_string  is  ‘||,  and  the 
default  x_repeat  is  1. 

RETURNS:  Number  of  carriage  returns  printed. 

(print-size  ’g_value  [\_maximum])  [LISP  Function] 

RETURNS:  The  number  of  characters  needed  to  print  g_value,  or  x_maximiim,  whichever 

is  smaller. 

BUG:  A  line  feed  in  a  string  value  counts  as  one  character. 

*ptime-counts-per-second*  [LISP  Global  Constant] 

VALUE:  The  number  of  ticks  per  second  of  the  ptime  function  clocks. 

(puresegment  ’s_type  ’x_3ize)  [LISP  Function] 

EQUIVALENT  TO:  {segment  's_type  ’x^size)  but  the  resulting  segment  is  allocated  to  pure 
memory  and  is  never  garbage  collected. 

(round  n^number)  [LISP  Function] 

RETURNS:  The  nearest  integer  to  n_number. 
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(search-path  ’(s_clirectory  ...)  's_file  j‘s_modej)  LISP  Function! 

WHERE:  'S^mocle  is  either  V  for  ’’read*’,  'w  Tor  "write”,  or  ’«  Tor  "aj)peiul".  and  defaults 
to  V. 

RETURNS:  An  interned  symbol  naming  a  file  which  has  a  name  of  the  form 

s_directory/s_file.  For  the  r  s_mode,  s_directory  is  the  first  symbol  in  the 
list  ’(s_directory  ...)  for  which  the  file  s_directory/s_file -exists,  but  nil  is 
returned  if  no  such  file  exists.  For  the  ly  s_mode,  s^directory  is  just  the  first 
symbol  on  the  list  *(s_directory  ...),  for  which  the  directory 

s_directory/s^ubdirectory  exists,  where  s_subdirectory  is  the  directory  part 
of  s_file  (see  split-filename).  For  the  a  s_mode,  s_direct.ory  is  as  for  the  r 
s_modc  if  some  file  exists,  and  otherwise  as  for  the  w  s_mode. 

No  check  is  made  for  file  readability,  writability.  or  cieatabilitv  just 
existence. 

For  s_directory  equal  to  the  symbol  |.|,  the  name  s_file  is  used  in  place  of 
./s_file.  If  s_file  begins  with  a  slash  (/)  or  tilde  ('),  no  search  is  done,  but  the 
existence  of  the  file  or  subdirectory  is  checked  for.  and  nil  returned  if  the  file 
or  subdirectory  does  not  exist. 


sfe_assert  {g_test.  t_message)  C  Macro) 

sfe_assertl  {g_test,  t_message,  g_argument_l)  'G  Macro) 

sfe_assert2  (g^test,  t^message,  g«argument_l,  g_argument_2)  [C  Macro) 

sfe_assert3  (g_test,  t_message,  g_argument_l,  ...,  g_argument_3)  [C  Macro) 

sfe_assert4  (g_test,  t^message,  g_argument_l,  g_argument_ l)  C  Macro) 

sfe_assert5  (g_test,  t_message,  g_argument_l,  ...,  g_argument_5)  Macro) 

SIDE  EFFECT:  Evaluate  g_test  and  if  false  (zero)  call 


5/e_error  (t^message,  g_argument_l,  ...) 

and  then  execute  sfe_return,  which  is  a  macro  that  defaults  to  return  (0). 

The  digit  at  the  end  of  sfe^assert  counts  the  number  of  g_argument’s. 
The  C  macro  preprocessor  will  complain  if  it  is  wrong. 

sfe_check  ()  [C  Macro) 

SIDE  EFFECT:  If  the  error  flag  set  by  sfe^error  is  on,  executes  the  sfe^returu  macro, 
which  by  default  does  a  return  (0). 
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sfe.error  (t^format,  g_argument,  ...)  jC  Function] 

SIDE  EFFECT:  An  error  flag  is  set,  and  the  arguments  cause  an  error  message  string  to  be 
produced  after  the  manner  of  sprintf. 

When  control  returns  to  LISP,  the  ccheck  function  will  see  the  error  flag, 
reset  it,  read  the  error  message  string  using  read,  and  send  the  value  read 
to  error. 

The  error  flag  can  also  be  tested  using  the  C  macros  sfe^check  and 
sfe^iserror. 

The  error  message  must  be  a  ren(/able  LISP  value. 

sfe_iserror  ()  [C  Macro] 

RETURNS:  True  if  the  error  flag  set  by  sfe_error  is  on.  False  otherwise. 

SFEJ.INT  [C  Macro] 

VALUE:  1  if  lint  is  running,  0  if  not. 

sfe_return  [C  Macro] 

DEFAULT:  return  (0) 

USE:  Executed  by  sfe^assert  and  sfe_check  in  order  to  return  from  the  current  function 
upon  detecting  an  error.  Can  be  changed  if  0  is  not  acceptable  as  a  return  value. 


SFE_VAX 

[C  Macro] 

SFE_68XXX 

[C  Macro] 

SFE_BSD 

[C  Macro] 

SFE_SUN 

[C  Macro] 

SFE_FRANZ 

[C  Macro] 

SFE_SKETCH 

(C  Macro] 

VALUE;  If  a  SKETCH  is  running  on  a  DEC  VAX  processor, 

SFE_VAX  is  non-zero  and 

equals  the  type  number  of  the  processor:  e.g.  780,  785,  etc.  If  a  SKETCH  is  run¬ 
ning  on  a  MOTOROLA  68000  processor,  SFE^68XXX  \s  non-zero  and  equals  the 
type  number  of  the  processor:  e.g.  68010,  68020,  etc. 


If  a  SKETCH  is  running  under  a  Berkeley  Software  Distribution  version  of 
UNIX,  SFE^SD  is  non-zero  and  equals  the  version  number  of  the  distribution. 
If  a  SKETCH  is  running  under  a  SUN  Microsystems  version  of  UNIX,  SFE_SUN 
is  non-zero  and  equals  the  version  number  of  the  distribution. 

If  a  SKETCH  is  using  Franz  LISP,  SFE^FRANZ  is  non-zero  and  equals  the  ver¬ 
sion  number  of  the  Franz  LISP  being  used. 

SFE^SKETCH  is  always  non-zero  and  equals  the  version  number  of  SKETCH 
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that  is  being  used. 

Software  version  numbers  are  written  <is  a  version  number  followed  by  six 
digits:  the  first  3  for  the  minor  version  number,  and  the  next  three  for  the  micro 
version  number.  E.g.,  4.3  is  written  4003000,  while  42.16.1  is  written  42016001. 
Where  versions  are  denoted  as  ‘a’,  ‘b\  etc.,  these  are  represented  by  1,  2,  3. 

The  macros  just  described  are  always  defined:  they  equal  zero  if  their  hardware 
or  software  is  not  being  used. 

^sketch-version*  [LISP  Global  Constant) 

franz-version  [LISP  Global  Constant] 

VALUE:  These  are  the  version  numbers  of  the  SKETCH  and  FRANZ  LISP  that  are  being 
used.  They  are  floating  point  numbers,  generally,  with  the  major  version 
number  as  the  integer  part,  and  each  minor  verson  number  as  three  decimal 
places.  Thus  FRANZ  version  42.16.1  is  represented  by  42.016001.  Minor  ver¬ 
sions  *a\  ‘b’,  ‘c\  etc.  are  represented  by  1,  2,  3,  ...  (and  given  3  decimal  places). 
Thus  SKETCH  version  4b  is  represented  as  4.002. 

(split-filename  's_file)  [LISP  Function 

RETURNS:  The  pair  (s_directory  s_basename)  such  that  s_file  is  eciuivalent  to— 

s_di  rectory /s_basename 

If  there  is  no  slash  /  in  s_file,  s_directory  equals  ’|  j.  Slashes  are  removed 
from  the  end  of  s_directory.  Thus  an  s_directory  value  of  ’||  means  the  root 
directory. 

(stringopen  ’t_string  'x_size  's/t_mode  [’t_name])  [LISP  Function] 

WHERE:  X_j5ize  is  the  number  of  bytes  in  t_string.  Currently  the  best  way  to  get  such  a 
string  is  to  call  [pxireseginent  ^string  x_pages)  where  x_size  =  512  *  x_pages. 
T_name  is  the  name  of  the  port,  and  defaults  to  ’stringfile". 

RETURNS:  If  s/t_mode  is  ^r  (or  ’V**),  returns  a  port  which  when  read  from  will  read  the 
string.  An  end  of  file  will  occur  after  the  x^size^th  byte.  An  end  of  file  will 
not  occur  before  a  NUL  byte:  the  NUL  byte  will  be  read. 

If  s/t_mode  is  Vs  (or  "rs"),  behaves  as  for  V,  but  an  end  of  file  will  occur  just 
before  the  first  NUL  byte  in  the  string,  if  there  is  one,  or  after  the  x_sizeTh 
byte,  if  there  is  no  NUL. 

If  s/t_mode  is  ^w  (or  ”w*’),  returns  a  port  which  when  written  will  write  into 
the  string.  An  end  of  volume  is  returned  when  trying  to  write  beyond  the 
x_sizeTh  byte. 

If  s/t_mode  is  ^a  (or  behaves  just  as  for  Vv,  but  sets  the  initial  position 
of  the  port  to  the  first  NUL  byte  in  the  t_string,  or  just  after  the  end  of 
t_5tring  if  there  are  no  NUL  bytes. 
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If  s/t_mocie  is  \\s  or  ^as  (or  *'ws"  or  "as")  behaves  like  ’w  or  'a.  but  writes 
NUL  s  into  the  part  of  the  string  to  be  written,  and  arranges  for  an  end  of 
volume  just  before  the  last  byte  of  the  string  (which  is  NUL).  Ensure.s  there 
is  a  NUL  in  the  string.  If  ^as  is  used  with  a  string  that  has  no  NUL,  the  last 
byte  of  the  string  is  set  to  NUL. 

The  close,  drain,  terpri,  /seek,  and  nwritn  functions  can  be  used  on  these  ports 
in  the  normal  way. 

The  string  may  be  used  as  a  normal  string  after  the  port  is  closed,  as  long  as 
the  string  is  NUL  terminated. 

NOTE:  Fseek  can  be  use  to  determine  the  location  of  the  current  position  in  one  of  these 
ports  relative  to  the  beginning  of  the  string,  and  to  reset  that  position. 


Nwritn  can  be  used  to  determine  the  number  of  characters  between  the  current 
position  and  any  previous  line  feed  in  the  string,  or  the  beginning  of  the  string  if 
there  is  no  previous  line  feed. 


*top-IeveI-init* 

LISP  Global  Variable; 

*top-Ievel-init-started* 

IlISP  Global  Variable) 

*top-level-exit* 

;LISP  Global  \"ariable; 

*  top-Ievel-p  rom  p  t  * 

[LISP  Global  Variable) 

*top-level-read  * 

[LISP  Global  ^'’ariablej 

*top-Ievel-evaI* 

[LISP  Global  Variable) 

*  top-level-print* 

[LISP  Global  \'ariable] 

*top-level-times* 

[LISP  Global  Variable) 

*  top-  level-  p  rin  t- times  * 

jLISP  Global  \'ariablej 

*top-level-init-times* 

[LISP  Global  X'^ariable] 

*top-level-saved-times* 

[LISP  Global  Variable) 

*top-Ievel-saved-print-times* 

[LISP  Global  Variable) 

*top- level-threshold-time* 

[LISP  Global  Variable) 

+ 

[LISP  Global  Variable) 

++ 

[LISP  Global  Variable) 

+++ 

[LISP  Global  Variable) 

* 

[LISP  Global  Variable) 

** 

[LISP  Global  Variable] 

* 

[LISP  Global  Variable) 

VALUE:  The  top  level  executes— 
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{selq  *top-Uvel-init-started*  l) 

{funcall  *  top-level- i  nit*) 

(find  and  load  the  {status  top-level- tc- files)) 

(remove  and  process  any  —/and  —E  options  at  the 
the  beginning  of  the  argument  list) 

'  [setq  *top-level-saved-times*  *top-level-times*) 

[setq  *top-level-SQved-print- times*  *top-level-print-times*) 

[setq  *top-level-init- times*  [funcall  *top-level-SQved-times*)) 

[if  [and  *is-compiler*  [there  are  more  arguments)) 

(process  arguments  as  for  liszt  compiler  and  exit)) 

just  before  printing  the  first  prompt  after  loading.  It  never  executes  this  again 
during  the  current  process,  but  will  re-execute  it  when  the  process  is  first 
dumped  by  dumplisp  and  then  the  resulting  file  is  czee’ed. 

*iop-level-init-siaried*  is  nil  from  the  beginning  of  loading  until  the  execution  of 
the  above. 

The  top  level  then  begins  the  read-eval-print  loop,  which  is  roiighly- 

[let  ((prompt  *  top-level-prompt*) 

(read  *  top-level-read*) 

(times  *top-level-times*) 

(eval  *  top-level- eval*) 

(print  *  top-level-print*) 

(print-times  *top-level-print-times  ^) 
expression  value  pre-eval-times  post-eval-times) 

[funcall  prompt  p_port) 

(scig  expression  [funcall  read  p_port  g_eof-value)) 

...  check  for  read  errors  and  end  of  file  ... 

[setq  pre-eval-times  [funcall  times)) 

[setq  value  [funcall  eval  expression) 

(seig  post-eval-times  [funcall  times)) 

(sei^  ++ 

+  expression) 

[setq***  ** 

**  * 

*  value) 

[funcall  print  value  p_port) 

[funcall  print-times  post-eval-times  pre-eval-times  p^port))) 

Here  the  various  functions  used  are  saved  at  the  beginning  of  the  read-eval-print 
loop  iteration,  so  any  changes  made  to  them  will  not  become  effective  till  the 
next  iteration.  Changes  to  these  functions  should  be  synchronized  by  including 
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them  in  a  single  progn  which  is  read  all  at  once  by  the  reader. 

Any  call  to  the  exit  function  results  in  executing 

(Juncall  *  top-level- exit*) 

[Juncall  *iop-level-saved-print- times* 

(funcall  *top-level-saved- times*) 

*top-level-init- times*  poport) 

before  the  normal  exit  actions  are  taken.  Here  again  the  values  of  *top-level- 
times*  and  *top-level-print-times*  have  been  saved  when  *top-level-init- times* 
was  set,  to  avoid  incompatibilities  when  these  variables  are  reset. 

BREAK  AND  TRACE:  Break  and  trace  also  use— 

*  top- level- prompt  * 

*top-level-read* 

*  top- level- eval* 

*  top-level-print* 

In  addition  the  top  level  values  of  the  global  variables  *  line- length*, 
prinlengfh.  and  prinlevel  are  temporarily  restored  every  time  *  top- 
level-print*  is  called. 

DEFAULT  VALUES: 


*top-level-init* 

A  no-operation  function. 

*top-level-times* 

A  function  that  retuns— 

, (number  gc’s)). 

*top-level-print- times* 

A  function  that  prints  execution  times  if  the 
total  time  is  larger  than  *top-level- 
threshold-time*  seconds. 

*  top-level-threshold-time* 

1.0 

*  top- level-prompt* 

A  function  that  prints  "— > 

*  to  p-  lev  e  1-  re  ad  * 

read 

*top-level-eval* 

eval 

*  top- level-print* 

pretty-print 

(sstatus  top-level-rc-files  (s_rc-file  ...))  [LISP  Function) 

(status  top-level-rc-files)  [LISP  Function] 

SIDE  EFFECT:  Whenever  a  LISP  environment  is  loaded  by  UNIX,  then  after  the  function 
specified  by  *top-level-init*  is  called,  the  list  of  files  s_rc-file  ...  is  examined 
to  find  the  first  file  that  exists,  and  that  file  is  loaded.  If  none  of  the  files 
exists,  no  action  is  taken.  The  load-search-path  is  not  used  to  locate  the 
files. 


DEFAULT  V.^UE:  In  sketch  the  default  value  is— 

{sketch.rc  .. /sketch. rc  ../../sketch.rc  ''/sketch. rc) 
and  in  the  compiler,  sketchcom,  the  default  is 
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{sketchcom.rc  ,,/$ketclico7n.rc  ../../sketchcom  rc  /sketcliconi.rc). 

(sstatus  top-levei-switches  (s_switch  ...))  [LISP  Function] 

(status  top-levei-switches)  [LISP  Function] 

SIDE  EFFECT:  Whenever  the  argument  list  to  the  current  LISP  environment  begins  with 
one  of  the  switches  in  the  s_switch  list,  that  switch  and  any  following 
arguments  it  requires  are  processed  after  the  *top-ltvel-init*  function  is 
called  and  any  top-Uvel-rC’ files  file  loaded.  To  be  processed  the  switch 
must  be  one  of  the  following- 


-I  file-name 

The  file  is  /ond’ed,  using 
load-search-patli  to  find  the  file. 

-E  "expression'* 

The  expression  is  read  and  evaluated. 

Arguments  processed  by  this  mechanism  are  removed  from  the  list  of 
UNIX  command  arguments  by  using  the  argv-shift  function.  Errors 
encountered  while  processing  these  arguments  will  cause  the  program  to 
exit  with  an  e.xit  code  of  2. 

DEFAULT  V.ALUE: 

H-E). 


(use-ptport  'p^port)  [LISP  Function] 

USE  ONLY  WHEN:  Writing  C  or  FORTRAN  functions  that  do  their  own  printing.  Helps 
obey  the  conventions  involving  ptport  (which  is  used  by  demo). 

RETURNS:  t  if  output  sent  to  p_port  is  also  to  be  sent  to  ptport  according  to  the  stan¬ 
dard  conventions  for  using  ptport. 

EXAMPLE: 

(ccheck  (_xxx_print  port  ...)) 

(if  (use-ptport  port)  (ccheck  (_xxx_print  ptport  ...))) 

(vrefi-double  W^vector  ’x_index)  [LISP  Special  Function] 

EQUIVALENT  TO:  Vrefi-long  but  for  flonum’s,  i.e.  double  precision  floating  point 
numbers.  Can  be  setf.  A  flonum  index  is  in  8  byte  units  (0  is  the 
beginning  of  V^vector). 
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(vsize-long  V_vector)  [LISP  Funct  ion) 

(vsize-double  V_vector)  [LISP  Function] 

RETURNS;  The  number  of  a-long's  or  a-double's  in  a  vector. 

(xtime  ’g_e\'pression)  [LISP  Function] 

RETURNS:  The  time  in  seconds  taken  on  the  average  to  execute  g_expression.  To  com¬ 
pute  this,  g_expression  is  executed  many  times,  until  several  seconds  have 
passed.  The  time  reported  is  the  average  time  in  seconds  of  one  execution, 
excluding  time  taken  by  the  garbage  collector. 
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1-  INTRODUCTION.  A  SKETCH  atom  is  a  number,  pointer,  or  small  structure 
that  is  passed  as  an  argument  or  return  value  by  copying  the  atom  itself,  rather  than  by 
copying  a  pointer  to  the  atom.  (It  is  not  to  be  confused  with  a  LISP  atom,  which  is  any 
object  that  is  not  a  non-empty  list  or  hunk,  and  is  an  anachronism  to  be  avoided.) 

The  atoms  required  by  SKETCH  are  numbers  and  pointers  to  LISP  values.  Most  of 
this  ATOMS  package  is  concerned  with  interfacing  these  atoms  to  the  C  language. 

2.  NUMERIC  ATOMS.  The  numeric  atom  types  supported  by  SKETCH  are  listed  in 
Table  ^4.1.  AW  the  types  but  a-ubxt  and  an-lbtt  have  C  type  names:  e.g.  char.  The  C  types 
uchar,  usliort^  and  ulong  are  standard  SKETCH-dehned  abbreviations  for  unsigned  char, 
unsigned  short,  and  unsigned  long,  respectively. 

.\11  the  types  except  int  and  unsigned  have  associated  SKETCH  types  (see  the 
SKETCH  OBJECTS  package  chapter),  such  as  u-Jloat,  and  can  therefore  be  designated  as 
the  element  types  of  SKETCH  arrays  (see  the  SKETCH  ARR.AYS  Package). 

.\11  the  types  store  numbers,  except  the  an-lbit  type,  which  stores  nit  or  /, 
represented  in  C  as  an  off  bit  or  an  on  bit  respectively. 

Several  of  the  types  can  be  used  for  arguments  to  C  functions.  These  have  an  asso¬ 
ciated  Argument  Prefix:  e.g.  /_  for  double  precision  floating  point.  The  .t_  prefix  for  inCs 
and  the  /_  prefix  for  doublets  were  chosen  to  be  the  same  as  the  prefixes  for  the 
corresponding  LISP  argument  types,  fixnuin  and  flonuin. 

Most  of  these  types  have  C  macros  or  global  variables  equal  to  the  minimum  and 
maximum  numeric  values  storable  in  variables  of  the  type  (of  course  0  is  the  minimum 
value  for  unsigned  integers).  For  example, 

i/(x  >  SAT^CMAXIMUM)  x  =  SAT_CMAXIMUM; 
else  if  (x  <  SA  T^CMINIMUM)  i  =  5A  T_CMINIMUM; 

clips  a  value  stored  in  a  variable  x  if  that  value  is  outside  the  range  of  a  char  variable. 

The  signed  number  types  have  a  special  value  which  denotes  a  missing  value.  E.g. 
SAT^CMISSING  is  stored  in  a  char  variable  to  denote  a  missing  value.  In  LISP  missing 
values  are  denoted  by  nil.  Thus  if  the  value  of  a  SKETCH  array  element  with  type  a- 
char  is  returned  to  LISP,  the  missing  value  will  be  returned  as  nil. 

However,  C  routines  that  return  integers  or  floating  point  numbers  to  LISP  cannot 
return  nil,  which  is  not  a  number.  They  must  return  either  a  fixnum  or  Jloninn,  and  use 
the  values  stored  in  the  LISP  Global  Constants  ^SAT^IA4ISSING  or  ^SAT_DMISSING, 
respectively,  to  denote  the  missing  value.  These  LISP  constants  are  ecjual  numerically  to 
the  corresponding  C  constants  SAT_IMISSING  and  SA  T^DMISSING. 
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TABLE  4.1 

SKETCH  NUMERIC  ATOM  TYPES 

C  Type 

Size 

C  Minimum 

Value 

Arg. 

Meaning 

In 

SKETCH 

Prefix 

Bits 

C  Maximum 

LISP  Missing 

Type 

1-bit  true/false 

1 

an-lbit 

logical  bit 

— 

1-bit  unsigned 

1 

0 

a-ubit 

integer 

1 

uchar 

8-bit  unsigned 

8 

0 

a-uchar 

integer 

5.-1  T UCMAXIMUM 

char 

8-bit  signed 

8 

5.4  T_CMINIMUM 

54  T_CMISS[XG 

a-char 

integer 

5.4  T CMAXIMUM 

— 

ushort 

16-bit  unsigned 

16 

0 

a-ushort 

integer 

5.4  T US\[AX[.\fU.\{ 

short 

16-bit  signed 

16 

5.4  T_S.\4IXIMUM 

5.4  T_SM/SSIXG 

a-short 

integer 

5.4  T SMAXIMUM 

— 

ulong 

ulx_ 

32-bit  unsigned 

32 

0 

a- u  long 

integer 

5/1  T.ULMAXIMUM 

long 

lx_ 

32-bit  signed 

32 

5/1  T_LMINIMUM 

54  T_LMISSIXG 

a-Iong 

integer 

5/1  T LMAXIMUM 

— 

unsigned 

ux_ 

32-bit  unsigned 

32 

0 

— 

integer 

SAT UMAXIMUM 

int 

x_ 

32-bit  signed 

32 

SATJMINIMUM 

5/1 TJMISSING 

— 

integer 

5/1 TJMAXIMUM 

SAT I.\IISSING 

float 

32-bit  floating 

32 

5A  T_FMINIMUM 

SAr_F\{ISSING 

a-float 

point  number 

5A  T FMAXIMUM 

— 

double 

f_ 

64-bit  floating 

64 

5A  T_DMINIMUM 

SAT^DMISSING 

a-double 

point  number 

5.4  T_DMAXIMUM 

_5'4  r_DMISSlNG 

3.  NUMERIC  FUNCTIONS,  The  ATOMS  Package  contains  some  miscellaneous  C 
functions  and  macros  for  handling  numbers,  such  as  sat^ronnd  for  converting  a  floating 
point  number  to  a  long  integer  after  scaling  and  rounding.  These  are  listed  with  a  brief 
explanation  in  Table  4.2.  See  the  glossary  for  details. 

4.  FOREVER  IN  C.  The  macro  forever  is  defined  to  be  'for  (;;f  as  an  aid  to  writing 
more  readable  code. 
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TABLE  4.2 

C  LANGUAGE  NUMERIC  FUNCTIONS  AND  MACROS 

sat_ceiling  (f_number,  x«exp) 

The  smallest  lo7\g  integer  that  is  not  less 
than  renumber  times 

sat_floor  (f_number,  x_exp) 

The  largest  long  integer  that  is  not  greater 
than  renumber  times 

sat_log  (f_number) 

The  logarithm  base  2  of  the  smallest  i)Ovver 
of  2  greater  than  or  equal  to  the  absolute 
value  of  f_number,  or  SAT^IMISSL\G  if 
f number  is  0. 

sat_mad  (lx_ml,  lx_m2, 
lx a,  lx d) 

(Ix_ml*lx_m2+lx_a)/l.\_d.  The  product  and 
sum  are  stored  internallv  as  G-l-bit  integers 

sat_mas  (lx_ml.  Ix_m2, 
iix_aO,  x_al, 
x_shirt) 

( lx_m  1  *  lx_m  2  -f  2^‘ *  x_a  1  -fu  x_a0 )  <  < 

x_shift.  The  product  and  sum  are  stored 
internally  as  64-bit  integers.  If  x_shift  <  0. 
then  the  shift  is  a  right  shift  by  — x shift. 

sat_rmas  (lx_ml,  lx_m2) 
sat_rset  (x^shift) 
sat_rdeclare 

Some  macros  that  permit  a  set  of  sat^nias 
operations  to  be  done  with  a  common 
x_shift  value,  and  with  common  ux_a0  and 
x_al  values  which  round  the  shifted  result  if 
x shift  <  0. 

sat_round  (f_number,  x_exp) 

Converts  Lnumber  to  a  long  integer  by  mul¬ 
tiplying  it  by  2^'^P  and  then  rounding. 

5.  YES,  NO,  AND  EXCEPTION  IN  C.  To  represent  the  concepts  of  yes,  no,  and 
there-was-an-exceptional-case,  the  following  macros  have  been  defined  as  aids  to  writing 
readable  code— 


SAT_NO  (comment)  0 

SAT_YES  (comment)  1 

SATJEXCEPTION  (comment)  -1 

The  comment  can  be  any  legal  C  macro  argument  (it  must  not  contain  commas). 
Some  examples— 
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return  (SAT^YES {every thing  was  done  OK)); 

return  (SAT^NO  (we  could  not  find  the  body)); 

return  (SAT^XCEPTION [the  number  is  too  big  to  compute  with)); 

6.  LEFT-TO-RIGHT  AND  RIGHT-TO-LEFT  COMPUTERS.  A  left-toright 
computer  stores  integers  with  the  highest  order  byte  at  the  lowest  address.  Thus  when 
bytes  are  printed  left  to  right  in  order  of  increasing  address,  the  highest  order  byte  is 
printed  leftmost,  as  people  are  accustomed  to  seeing  it. 

A  right-to-left  computer  stores  integers  with  the  lowest  order  byte  at  the  lowest 
address.  Thus  when  bytes  are  printed  right  to  left  in  order  of  increasing  address,  the 
highest  order  byte  is  printed  leftmost,  as  people  are  accustomed  to  seeing  it. 

IBM,  Motorola,  and  related  computers  are  generally  left-to-right.  DEC  and  INTEL 
computers  are  generally  right-to-left. 

No  matter  what  type  the  computer  is,  bit  arrays  are  stored  as  if  the  computer  was 
left-to-right.  This  is  because  I/O  devices,  such  as  frame  buffers,  standardly  use  this 
method  of  storage. 

In  C  the  macro  SAT^EFT_TO_RlGHT  is  defined  as  I  if  the  computer  is  a  left-to- 
right  computer,  and  0  if  it  is  right-to-left.  The  LISP  global  variable  *left-to-riglit*  is 
similarly  defined.  Lastly,  there  is  a  utility  function,  integer-to-bytes,  to  convert  an  integer 
into  a  list  of  bytes  according  to  the  machine  type. 

7.  LISP  VALUES  IN  C.  LISP  values  are  designated  in  SKETCH  as  having  the 
sat^lvalue  C  type  and  the  g^  argument  prefix.  All  LISP  values  are  pointers  to  LISP 
objects:  even  fixnum^s  are  represented  by  a  pointer  to  an  integer  stored  in  garbage  collec¬ 
tible  memory.  A  LISP  value  (i.e.  the  object  it  points  at)  can  be  of  many  different  sub- 
types:  e.g.  list^Sf  fixnum^s,  symboFs,  etc.  Table  4.3  lists  these  subtypes,  the  C  names  for 
the  elements  of  the  subtypes,  and  the  C  function  usable  to  create  a  new  LISP  object  of 
the  given  subtype. 

Each  subtype  is  known  in  three  different  ways:  to  LISP  it  is  known  by  a  symbol 
returned  by  the  LISP  typep  function;  to  SKETCH  it  is  known  by  a-type  value  returned  by 
the  has-type  macro  (see  the  SKETCH  OBJECTS  package);  and  to  C  it  is  known  by  the 
soh^type  value  returned  by  the  sob^ltype  macro  (also  see  the  SKETCH  OBJECTS  pack- 
age). 

Whenever  C  code  allocates  a  new  LISP  object,  the  garbage  collector  may  be  called, 
and  will  destroy  any  previous  LISP  objects  that  is  not  referencible  by  starting  from  the 
global  variables  or  the  LISP  local  variables  on  the  LISP  (not  C)  stack.  If  C  code  allocates 
two  LISP  objects  before  returning  to  LISP,  it  must  store  the  LISP  value  pointing  to  the 
first  object  in  some  place  where  it  will  be  referencible.  A  good  place  is  inside  some  other 
LISP  object  that  is  referencible,  such  as  one  passed  as  an  argument  to  the  C  function  by 
LISP  code,  or  a  global  variable.  C  local  and  global  variables  are  not  referencible. 

8.  STRINGS.  LISP  values  that  are  strings  are  in  fact  C  char  *  pointers  to  NUL  ter¬ 
minated  C  strings.  The  argument  prefix  L  is  used  for  both  LISP  and  C  string  arguments. 


Printed  April  27,  1989 


ATOMS 


4-5 


TABLE  4.3:  PART  I 

LISP  VALUES 

iypcp  Type 
has-type  Type 
sob^ltype  Type 

Expression 

Meaning 

fixnum 

a-fixnum 

SOB_FIXNUM 

g value“> 

The  int  value  of  a  fixnum. 

sat nfixnu77i  fx n) 

Creates  a  new  fixnum  =  x n. 

sat^iisfixiinin  (x_n) 

Ditto  but  requires  that  —128  <  x_n 
<  255  and  is  more  efficient. 

flonum 

a-flonum 

SOBJPLONUM 

K value— >  sat ldoiiblc 

The  double  value  of  a  flonum. 

sat^nflonum  (f_n) 

Creates  a  new  flonum  =  f_n. 

string 

a-string 

SOB.STRING 

&  g_value— >5a/_/r/iar 

The  char  value  of  a  string.  The 

string  is  a  normal  NUL  terminated  C 
string. 

list 

a-list 

SOB_LIST 

sat^lfirst 

The  first  element  of  a  list  (i.e.  the 
car) 

^value— >5aC/re5^ 

The  restl  of  a  list  (i  e.  the  cdr). 

sat^nlist  (g_first,  g_rest) 

Creates  a  new  list  with  given  first 
element  and  rest  of  list. 

sat^nil 

The  nil  value. 

hunkO 

hunkl 

hunk2 

hunks 

hunk4 

hunks 

hunks 

a-hunk 

SOBjnJNK 

g_value— > 
5a^_/it;a/ue[x_inclex] 

The  x_index+lst  element  of  the 
hunk:  i.e.  the  (cxr  x_index  g_value), 
value. 

g_value— > 

The  first  element  of  the  hunk:  i.e.  the 
car  of  the  hunk. 

g_value— >  sat^lrest 

The  restl  element  of  the  hunk:  i.e. 
the  cdr  of  the  hunk. 

sat^nhunk  (x_size) 

Creates  a  new  hunk  with  x_size  ele¬ 
ments  all  set  to  nil. 

sat^empty 

If  a  hunk  is  supposed  to  have  x_size 
elements,  it  actually  has  more  ele¬ 
ments  if  x^ize  is  not  a  power  of  2, 
and  the  extra  elements  are  set  to 
sat_e7npty. 
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TABLE  4.3:  PART  H 

LISP  VALUES 

iypcp  Type 
has-typc  Type 
sob^ltypc  Type 

Expression 

Meaning 

g_value— >5a/_5ua/iic 

The  value  element  of  the  symbol 
g value. 

g_value—> 

The  property  list  element  (head)  of 
the  symbol  g value. 

g_value— >  sat^sf unction 

The  function  definition  element  of 
the  symbol  g value. 

g_value— >  snt^slink 

The  hash  table  link  element  of  the 
symbol  Revalue, 

symbol 

a-symbol 

SOB.SYMBOL 

g_value-->  sat_spname 

The  print  name  element  of  the  sym¬ 
bol  g value. 

sat^nsymbol  (t_string) 

Returns  the  existing  symbol  with  the 
print  name  t_sti*ing,  if  one  exists  and 
is  in  the  hash  table.  Otherwise 
creates  a  new  symbol  with  print 
name  t_string  and  puts  it  in  the  hash 
table. 

sat^nil 

The  symbol  nil. 

sat^t 

The  symbol  /. 

sat^cnil 

The  value  stored  in  the  value  ele¬ 
ment  of  an  unbound  symbol. 

Printed  April  27,  1989 


ATOMS 


4-7 


TABLE  4.3:  PART  III 

LISP  VALUES 

typcp  Type 
has-typc  Type 
sob ltypc  Type 

Expression 

Meaning 

vector! 

an-immediate-vector 

SOB_IVECTOR 

g_value— >5a^_t;c/iar[x_index] 

The  x_indexd-lst  char  in  an 
immediate  vector. 

g value— >  sat^vuch(ir\\\nQ\e\] 

Ditto  for  xichar. 

g value— >5«Ct’5/ior/[x iiiclex| 

Ditto  for  short. 

g value— >5aCvt/5/iorf(x inclex 

Ditto  for  usliort. 

g value— >5aCi'/on(9(x inclex| 

Ditto  for  long. 

g value— >5«Ci’»/on<7[x inclexi 

Ditto  for  ulong. 

g value— >5a/t-;/?o«/[x indexl 

Ditto  for  float. 

g v  all!  e — >  .s  (/  /  vtl  ouble'  x i  n  cl  e  x . 

Ditto  for  double. 

g_value— >6a/_t;prop 

The  property  list  element  of 
an  immediate  vector. 

g_value— >  5a/_t’5ire 

The  size  of  an  immediate  vec¬ 
tor  in  bytes. 

sat^nivector  (x_size) 

Creates  a  new  immediate  vec¬ 
tor  with  x size  bytes 

vector 

a-lisp-vector 

SOB_L  VECTOR 

g^value— >  5aCi;v«/tie[x_index] 

The  x_index-fTst  element  of 
the  LISP  vector  g value. 

g_value— >5a/_vp/*‘5f 

The  property  list  element  of 
the  LISP  vector  g value. 

g_value  — >  sat_vsize 

The  size  of  the  LISP  vector 
g valiie  in  bytes. 

sat^nlvector  (x_size) 

Creates  a  new  LISP  vector 
with  x_size  elements. 
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TABLE  4.3:  PART  IV 
LISP  VALUES 


typep  Type 
has- type  Type 
sob^ltype  Type 

Expression 

Meaning 

array 

a-lisp-array 

SOB_LARRAY 

g^value— >  sat^afunction 

The  function  element  of  a  LISP  ar¬ 
ray. 

g value— >  sat^aaxiT 

The  aux  element  of  a  LISP  array. 

g value— >  sat a(lata 

The  data  element  of  a  LISP  array. 

g value— >5a/n/en(7//i 

The  length  element  of  a  LISP  array. 

g^value— >  sat^adelta 

The  delta  element  of  a  LISP  array. 

port 

a-port 

SOB.PORT 

g_value— >  satjport 

The  C  port,  or  FILE  *  value,  associ¬ 
ated  with  a  LISP  port. 

value 

a-value 

SOB^VALUE 

g_value— >  S(if_lvalue 

The  value  of  a  LISP  value  object. 

9.  FORMATING  READABLE  STRINGS.  There  are  several  C  functions  for  print¬ 
ing  strings  in  a  format  that  can  be  read  by  the  LISP  read  function.  For  e.\aniple.  an  arbi¬ 
trary  file  name  string  can  be  printed  to  be  read  as  a  symbol  by  the  LISP  reader  via  a  call 
such  as— 


prtri//(**(cannot  open  the  file  %s)*\  sat^sformat  (filename)); 
where  filename  is  a  C  char  *  string.  If  filename  were  to  equal— 

"/usr/foo/fancy" 

then  the  printf  would  print— 

(cannot  open  the  file  /usr/foo/fancy) 
but  if  filename  were  to  equal— 


•*#play** 

then  the  printf  would  print— 

(cannot  open  the  file  |#play|) 

Sat^tformat  is  a  similar  function  for  printing  a  string  so  it  will  be  read  as  a  string  by  the 
LISP  reader. 


Because  these  functions  return  a  pointer  to  a  static  character  string  buffer  allocated 
inside  the  function,  two  calls  to  one  of  these  functions  cannot  be  used  inside  one  call  to 
printf.  See  the  GLOSSARY  for  details. 
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10.  HITLIST.  Empty  for  the  moment. 

11.  GLOSSARY. 

[Argument  Prefix) 

DENOTATION:  In  C,  denotes  arguments  of  double  float  [double)  type.  In  LISP,  denotes 
arguments  of  flonum  type. 


forever  [C  Macro] 

equivalent  TO:  for 

(integer-to-bytcs  ’x_integer)  [Lisp  Function] 

RETURNS:  A  list  of  the  4  consecutive  bytes  (flxjuim^s  from  0  through  255)  that  would  be 
stored  consecutively  in  memory  to  represent  the  integer.  The  list  has  an 
order  on  right  to  left  machines,  such  as  VAX’es,  which  is  the  opposite  of  its 
order  on  left  to  right  machines,  such  as  68000’s. 

*left-to-right*  [LISP  Global  Variable] 

V.ALUE:  .\on-/ii7  if  computer  stores  bytes  in  an  integer  from  left  to  right  (high  order  to 
low  order,  like  IBM  and  MOTOROLA).  Nil  if  the  bytes  are  stored  from  right  to 
left  (low  order  to  high  order,  like  DEC  and  INTEL) 


lx_ 

[.Argument  Prefi.xj 

ulx_ 

[Argument  Prefix] 

DENOTATION:  In  C,  denotes  arguments  of  long  ini  [tong)  or 

unsigjied  long  inf  [tdong) 

type. 

PI 

[C  Macro] 

V.\LUE:  The  constant  tt. 

gjarray— >sat_afunction 

[C  Macro] 

g_I  ar  r  ay — >  s  at_aau  X 

[C  Macro) 

gjarray— >sat_adata 

[C  Macro] 

gjarray— >sat_alength 

[C  Macro] 

g_l  a  r  r  ay — >  s  at_ad  e  1 1  a 

[C  Macro) 

WHERE:  GJarray  must  be  a  LISP  array. 

VALUE:  The  various  parts  of  g^larray:  function,  aux,  data,  length,  and  delta.  Sat_adata 
is  a  pointer  to  the  array  data,  which  is  a  block  of  contiguous  memory  in  a  page 
with  the  appropriate  data  type  for  the  array  elements  [fixnum,  flonum^  or 
value). 

WHEN  ASSIGNED:  Changes  the  part  of  gjarray. 
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sat_ceiling  (f_number,  x_exponent)  [C  Function] 

V.M^UE:  A  long  equal  to  the  smallest  integer  greater  than  or  equal  to  f_number  times 
OX_expon«nt 


SAT_CMAXIMUM 

[C  Constant] 

SAT.CMINIMUM 

[C  Constant] 

SAT_CMISSING 

[C  Constant] 

SAT_UCMAXIMUM 

[C  Constant] 

SAT_SMAXIMUM 

[C  Constant] 

SAT_S  MINIMUM 

[C  Constant] 

SAT.SMISSING 

[C  Constant] 

SAT_USMAXIMUM 

[C  Constant) 

SATJLMAXIMUM 

[C  Constant] 

SATJLMINIMUM 

jC  Constant) 

SATJLMISSING 

[C  Constant) 

SAT.ULMAXIMUM 

[C  Constant) 

SAT_IMAXIMUM 

(C  Constant] 

SAT_IMINIMUM 

[C  Constant] 

SAT_IMISSING 

'C  Constant] 

SAT_UMAXIMUM 

[C  Constant] 

SAT_FMAXIMUM 

[C  Global  Variable] 

SAT_FMINIMUM 

[C  Global  Variable] 

SAT_FMISSING 

[C  Global  Variablej 

SAT_DMAXIMUM 

[C  Global  Variable) 

SAT_DMINIMUM 

[C  Global  Variable) 

SAT_DMISSING 

[C  Global  Variablej 

sat_cmissing  (x_number) 

[C  Macro] 

sat_3missmg  (x_number) 

[C  Macro] 

sat_lmissing  (x_n umber) 

[C  Macro) 

sat_imissmg  (x_number) 

[C  Macro] 

sat_fmissing  (f_number) 

[C  Macro) 

sat_d missing  (f_n umber) 

(C  Macroj 

V.\LUES:  The  constants  and  variables  are  the  largest  value,  smallest  value,  and  missing 

value  for  various 

data  types  according  to  the  table  below.  For  types  with  a 

missing  value,  the  missing  value  is  not  part  of  the  range  from 
SA  T_...MIMINIM  through  SA  T_... MAXIMUM  inclusive. 
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WARNING: 


WARNING: 


RETURNS: 


SAT_IMAXIMUM 
SAT_IMINIMUM 
SAT IMISSING 

ml 

SAT_UMAXIMUM 

unsigffed 

SAT_LMAXIMUM 

SATJLMINIMUM 

SATJLMISSING 

long 

SAT.ULMAXIMUM 

ulong 

SAT_S  MAXIMUM 

SAT_SMINIMUM 

SAT.SMISSING 

short 

S  AT_US  MAXIMUM 

ushort 

SAT.CMAXIMUM 

SAT_CMINIMUM 

SAT.CMISSING 

char 

SAT.UCMAXIMUM 

uchar 

SAT_FMAXIMUM 

SAT_FMINIMUM 

SAT_FMISSING 

float 

SAT_DMAXIMUM 

SAT_DMINIMUM 

SAT_DMISSING 

double 

On  some  IEEE  hardware, 

5/1  T^FMISSING  ==  5.4  T^FMISSING 
and 

5.4  T_DMISSING  ==  5.4  T_D  MISSING 

are  both  false.  Therefore  the  macros  sal^missxng  and  sat^dmissimj  have 
been  provided  to  test  for  missing  values. 

Some  C  compilers  cannot  convert  SAT_LLMAXIMUM  to  a  double  precision 
floating  point  number  properly:  they  insist  on  going  through  an  ini  as  an 
intermediate  step  and  get  -1.0  as  a  result.  To  ensure  proper  results  use— 

saUtUod  {SA  T_ULMAXIMUM). 

The  macros  sat^cmissingf  ...,  sat^dmissvxg  return  true  if  and  only  if  the 
number  they  are  testing  is  a  missing  value  of  the  given  type. 

The  tests  for  a  particular  type  of  missing  value  may  be  made  on  a  copy  of  the 
missing  value  held  in  a  variable  of  some  other  type,  provided  that  the  other 
type  is  large  enough  to  hold  all  values  of  the  missing  value’s  type.  E.g. 
SAT^CMISSING  may  be  copied  into  a  double  variable  and  tested  there  by 
sat^cmissing.  Similarly  SAT^MISSING  may  be  copied  into  a  double  vari¬ 
able  before  being  tested. 
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sat^cnil  [C  Constant] 

VALUE:  A  sat^lvalue  specially  used  as  the  value  of  unbound  symbols  and  in  other  places 
where  the  LISP  interpreter  needs  to  distinguish  a  missing  value  from  nil. 

_SATJ)MISSING  [LISP  Global  Constant] 

V.aLUE:  The  flonum  used  to  denote  the  double  missing  value  by  C  and  FORTRAN  code. 

sat_empty  [C  Constant] 

VALUE:  A  sat^lvalue  which  is  specially  used  as  a  value  for  unused  elements  at  the  end  of 
a  LISP  hunk.  E.g.,  a  3  element  hunk  is  actually  represented  by  a  4  element  hunk 
(rounding  the  length  up  to  a  power  of  2)  whose  last  element  is  equal  to 
sat_empty. 

sat_floor  (f_number,  x_exponent)  [C  Function) 

VALUE:  A  long  equal  to  the  largest  integer  less  than  or  equal  to  f_number  times 

*)X_*?xponcnt 

g_hunk— >sat_hvalue[x_index] 
g_h  u  n  k — >  sat_lfi  rst 
g_hunk— >sat_lrest 

WHERE:  G_hunk  must  be  a  LISP  hunk  or  the  value  sat^nil 

VALUE:  Sat_hvalue  [xjndexj  is  the  x^index-hTth  element  of  g_hunk.  Hunks  can  be  used 
like  dotted  pairs,  with  sat^ljirst  and  sat^lrest  accessing  car  and  cdr  of  the  hunk. 
These  are  the  first  two  elements  of  the  hunk,  but  the  order  of  these  first  two  ele¬ 
ments  is  implementation  dependent.  Sat_nil  may  be  treated  like  a  hunk  if  only 
the  first  two  elements  are  to  be  read;  both  these  will  equal  sat^nil. 

W'HEN  ASSIGNED:  Changes  the  element  of  g_hunk.  G_hunk  must  not  be  sat^nil. 

_SAT_IMISSING  [LISP  Global  Constant) 

VALUE:  The  fixnum  used  to  denote  the  int  missing  value  by  C  and  FORTRAN  code. 

Sc  g^string— >sat_lchar  [C  Macro] 

VALUE:  The  char  *  value  of  a  string  g_string.  This  string  ends  with  a  NUL  character,  as 
per  C  conventions.  Remember  the  *&’;  g^tring—> saC/cAar  is  just  the  first 
character. 


[C  Macro] 
[C  Macro) 
[C  Macro] 
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g_iiumber— >sat_ldouble  [G  Macro) 

VALUE:  The  double  value  of  a  flonum  g_number. 

SATJLEFT_TO^GHT  [C  Macro) 

V.\LIT:  1  if  the  high  order  byte  of  an  int  has  a  lower  address  than  the  low'  order  byte  of 

an  int,  so  that  printing  the  bytes  from  left  to  right  as  addresses  ascend  will  print 
the  high  order  byte  first.  0  otherwise,  in  which  case  printing  from  right  to  left 
will  print  the  high  order  byte  first, 

gjist— >sat_lfirst  [C  Macro] 

g_list— >sat_lrest  [C  Macro] 

SEE  ALSO:  Sat_hvalue. 

WHERE:  G_list  must  be  a  dotted  pair  {list  value)  or  the  value  ■s(it_nil. 

V.ALUE:  Saf^lfirst  i#  the  first  element  of  gjist,  and  sat_lrest  is  the  rest  of  g_list  after  the 
first  element.  If  gjist  is  sat^nil,  both  these  return  the  value  sat_7iil. 

when  ASSIGNED:  Changes  the  first  element  or  the  rest  of  gjist.  G_list  must  not  be 
sat^nil. 


g_number— >sat_lint 

V.-XLUE:  The  int  value  of  a  fixnum  g_number. 

jC  Macro] 

satjog  (f^number) 

[C  F unction] 

RETURNS:  The  logarithm  base  2  of  the  smallest  power  of  2  which  is  greater  than  or 
equal  to  the  absolute  value  of  f^number,  or  SAT_1M1SS1NG  if  f^iuimber  is  0. 

g-por  t— >  sat.lport 

jC  Macro) 

VALUE:  The  FILE  *  port  associated  with  a  LISP  port  object. 

sat_lvalue 

6- 

[C  Type) 
[.Argument  Prefix) 

VALUE:  A  lisp  value.  The  prefix  g_  is  used  in  the 
denote  such  a  value. 

documentation  of  C  functions  to 

g_  V  al  u  e — >  s  at  _1  V  alu  e 

VALUE:  The  value  of  a  LISP  value  object. 

[C  Structure  Element) 
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sat_mad  {lx_inultiplicancl,  Ix^nuiltiplier,  |C  macroj 

lx.acldend,  Ix^divisor) 

W'HERE:  All  arguments  are  automatically  cast  to  longs. 

RETURNS:  (multiplicand  *  multiplier  -f  addend)  /  divisor  as  a  long. 

NOTE:  The  numerator  is  computed  as  a  64  bit  signed  quantity  and  then  divided  to  pro¬ 
duce  a  32  bit  long  quotient. 

sat_mas  (lx_multiplicand,  lx_multiplier,  [C  macro) 

ux_addendO,  x_addendl.  x^shift) 

WHERE:  Multiplicand,  and  multiplier  are  automatically  cast  to  longs. 

RETURNS:  (multiplicand  *  multiplier  +  addendO  +  (addendl  <<  32))  <<  shift  as  a 
long. 

NOTE:  The  quantity  to  be  shifted  is  computed  with  64  bit  signed  arithmetic,  and  trun¬ 
cated  to  32  bits  after  shifting.  A  negative  <  <  shift  is  equivalent  to  >  >  -shift. 

sat_nfixnum  (x_number)  [C  Function] 

sat_nsfixnum  (.\_number)  [C  Macro] 

RETURNS:  A  satjlvalxie  equal  to  a  new  LISP  fixnutn  with  value  x_number.  Note, 

however,  that  if  x_nuinber  is  near  0  the  ftxnnm  returned  will  be  one  of  a 
small  table  of  constant  fixntnn^s  whose  iiat_ltnl.'s  cannot  be  changed. 

Sat^iisfixiinni  may  be  used  for  greater  efficiency  in  place  of  sai^nfixiutvi  when 
it  is  certain  that  x_number  is  in  the  range  from  -128  through  255  inclusive. 

SIDE  EFFECT:  May  call  the  garbage  collector  when  creating  a  new  fixniiin. 

sat_nflonum  (f_number)  [C  Function] 

RETURNS:  A  sat^lvalue  equal  to  a  new  LISP  jionum  with  sat^ldonble  value  Cnumber. 

SIDE  EFFECT:  May  call  the  garbage  collector  when  creating  a  new  flonnm. 

sat_nhunk  (x^size)  [C  Function] 

RETURNS:  A  satjlvalxie  equal  to  a  new  LISP  hunk  with  at  least  x^size  elements.  Actu¬ 
ally,  the  hunk  is  a  power  of  two  elements  in  size  (128  elements  is  the  ma.x- 
imum).  The  first  x_jsize  elements  are  set  to  sat^nil,  and  the  rest  to  satjemptxj. 

SIDE  EFFECT:  May  call  the  garbage  collector  when  creating  a  new  hxink. 
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sat_nil 

VALUE:  The  LISP  symbol  nil. 


[C  Constant] 


sat_nivector  (x_size)  [C  Function) 

RETURNS:  A  sat^lvalue  equal  to  a  new  LISP  immediate  vector  {vcctort)  object  with 
x_size  bytes.  Note  the  size  is  in  bytes.  The  sat^vprop  of  the  immediate  vec¬ 
tor  will  be  sat^nil. 

SIDE  EFFECT;  May  call  the  garbage  collector  when  creating  a  new  immediate  vector. 

sat_nlist  (g_first  g_rest)  [C  Function] 

RETITRNS:  A  sat^lvalue  equal  to  a  new  LISP  list  with  g_first  as  the  first  element  and 
g_rest  as  the  rest  of  the  list. 

SIDE  EFFECT;  May  call  the  garbage  collector  when  creating  a  new  list. 

sat_nlvector  (x_size)  [C  Function] 

RETURNS:  A  sat^lvalue  equal  to  a  new  LISP  vector  with  x_size  elements.  The  sat^vprop 

of  the  vector  will  be  sat^nil. 

SIDE  EFFECT:  May  call  the  garbage  collector  when  creating  a  new  vector. 

sat_nsymbol  (t_string)  [C  Macro] 

RETURNS:  A  sat_lvalue  equal  to  the  LISP  symbol  in  the  symbol  table  whose  print  name 
is  t^string.  If  this  symbol  does  not  already  exist,  a  new  symbol  is  created. 

SIDE  EFFECT;  May  call  the  garbage  collector  when  creating  a  new  symbol. 

sat_rmasN  (l.\_multiplier,  Ix^multiplicand)  [C  Macro] 

sat_rsetN  (x_shift)  [C  Macro] 

sat_rdeclareN;  [C  Macro] 

WHERE:  N  is  either  nothing,  or  is  one  of  the  digits  1,  2,  3,  or  4. 

SIDE  EFFECT:  Sat_rdeclareN  declares  the  variables  sliiftN,  roundNO,  and  rounrfNi; 
saCrsc^N  sets  these  variables;  and  sat^rmasN  uses  them. 

RETURNS:  Sat^rmasN  returns  lx_multiplicand  *  lx_multiplier  left  shifted  by  x^shift. 

The  64  bit  product  is  computed  and  shifted,  before  being  truncated  to  a  32 
bit  long.  If  x^shift  is  negative,  the  product  is  right  shifted  by  -  x^shift  with 
rounding  induced  by  rounefNO  and  roundNl  having  been  set  to  the  proper 
values. 

Sat^rmasN(x,y)  expands  to— 

sat^mas  {x,  y,  roundNO,  roundNl,  shiftN). 
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sat_round  (f_number,  x_exponent)  [C  Function] 

VALUE:  A  /onp  equal  to  f_number  times  rounded  to  the  nearest  integer. 


sat_3nformat  (t^tring,  x_count) 
sat_3format  (t^tring) 
sat_tn format  (t^tring,  x_count) 
sat_tformat  (t^tring) 


[C  Function] 
[C  Function] 
[C  Function] 
[C  Function] 


WHERE:  X_count  is  the  maximum  length  of  t_5tring  in  case  the  latter  is  not  NUL  ter¬ 
minated. 


RETURNS:  A  string  [char  *  pointer  to  a  static  area  inside  the  routine)  that  is  the  same  as 
t^string  reformatted  for  input  to  LISP  as  a  symbol  (for  sat^snformat  or 
sat^sformat)  or  as  a  string  (for  $at_tvforinat  or  sat^tformat).  For  symbols  not 
containing  any  special  characters,  t_string  is  returned  as  is  (or  more  pre¬ 
cisely,  a  copy  of  t^tring  in  the  static  area  is  returned).  In  all  other  cases, 
t^tring  is  surrounded  by  quotes  (|  or  ”),  and  a  backslash  is  prepended  to  any 
quote  or  \  characters. 

WARNING:  If  output  would  be  longer  than  4000  characters,  exclusive  of  surrounding  |’s 
or  **’s,  then  the  end  of  the  part  of  the  output  inside  the  |’s  or  "’s  may  be  trun¬ 
cated. 

WARNING:  The  same  static  area  is  used  by  all  calls  to  these  functions,  which  may  result 
in  strange  effects  unless  the  caller  finishes  with  the  result  of  one  call  before 
making  another  call.  Thus  the  call— 

print/ {*^%s  =  %s'\  $nt_sforniat  (x),  snt^tfonnat  (y)); 
will  not  work,  and  should  be  replaced  by  something  like 

char  temp  [lOOl]; 
temp[l000]  =  0; 


pri7itf{**%s  =  %s**,  5/rncpy  (temp,  $at_$format  [x),  1000), 
sat^tjormat  (y)); 


NOTE:  These  functions  are  contained  in  the  file  sat_csform.Cf  which  is  written  so  it  does 
not  have  any  /^include  statements,  and  can  be  moved  to  any  location  and  used 
independently  of  the  rest  of  SKETCH.  A  declaration  such  as— 

extern  char  *  sat^sfor7nat(),  *  sat^sn/ormatf), 

*  sat_tJormat(),  *  $at_tnformat(); 

will  be  required  in  SKETCH-independent  code  that  calls  functions  in  this  file. 
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g^symbol— >sat_svalue  [C  Macro 

g_symbol— >sat_3plist  [C  Macro 

g_3yinbol— >sat_sfunction  [C  Macro 

g^symbol— >sat_slink  [C  Macro] 

g_symbol—>sat_spname  jC  Macro! 


WHERE:  G_3ymbol  must  be  a  LISP  symbol. 

V.ALUE:  The  various  parts  of  the  symbol  object:  value,  property  list  (plist),  function 
definition  (function),  and  print  name  (pname). 

Sat^slink  exists  in  the  current  version  of  FRANZ  and  chains  to  the  next  entry  in 
a  hash  table  queue.  The  last  entry  has  sat^cnil  as  a  link  value. 

WHEN  ASSIGNED:  Changes  the  part  of  the  symbol  object.  The  link  and  print  name 
should  not  normally  be  changed.  G^symbol  should  not  be  sat^uil  or 
sat_t. 


sat_t  [C  Constant] 

VALUE:  The  LISP  symbol  t. 


sat_ultod  (uLx)  [C  Macro] 

RETURNS:  Ul_x  converted  to  a  double  precision  floating  point  number.  This  is  necessary 
because  some  C  compilers  do  not  do  it  right:  they  convert  to  int  as  an  inter¬ 
mediate  step,  and  thus  get  false  results  like  SAT_ULM.AXIMUM  ==  -1.0 


g_ivector— >sat_vchar[x_index]  [C  Macro! 

g^ivector— >sat_vuchar[x_index]  (C  Macro] 

gjvector— >sat_vshort[x_index|  [C  Macro] 

gjvector— >sat_vushort[xJndex)  jC  Macro] 

g_ivector— >sat_vlong[x_index]  [C  Macro] 

g_ivector— >sat_vulong[x_index)  [C  Macro] 

g_ivector— >sat_vfloat[x_index)  [C  Macro] 

g_ivector— >sat_vdouble[x_index]  [C  Macro] 

g_ivector— >sat_vprop  (C  Macro] 

g_ivector— >sat_vsize  [C  Macro] 


WHERE:  GJvector  must  be  a  LISP  immediate  vector  {vecton). 

VALUE: 

Sat^vchar  [x_index)  is  the  x_index+rth  char  of  g_ivector; 
sat^vuchar  [x.index]  is  the  x_index-l-l^th  uchar  of  gjvector; 
sat^vshort  [x^index]  is  the  xJndex-fTth  short  of  gjvector; 
sat^vushort  [x_index)  is  the  x_index+rth  ushort  of  g^ivector; 
sat_vlong  [x^index]  is  the  xjndex+l’th  long  of  g_i vector; 
sat_vulong  [x_index]  is  the  x_index+rth  ulong  of  gjvector; 
sat^vfloat  [xjndex]  is  the  xJndex-hTth  float  of  g_ivector;  and 
sat_vdouble  [x^index]  is  the  .xJndex-hTth  double  of  g^ivector. 

Sat^vprop  is  the  sat^lvalue  property  list  of  gjvector,  and  sat^vsize  is  the  size 
of  gjvector  in  bytes. 
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WHEN  ASSIGNED:  Changes  the  element  of  g^ivector. 


g_lvector‘“>sat_vvalue(x_index]  jC  Macro) 

g_l V ec tor— >sat_v prop  [C  Macro] 

g_lvector— >sat_vsize  [C  Macro) 

WHERE:  G.vector  must  be  a  LISP  vector. 

VALUE:  Sat^vvalue  (x_index)  is  the  sat_lvalue  x.index'fl’th  element  of  gjvector. 

Sat^xrprop  is  the  satjlvalue  property  list  of  gjvector,  and  sai_vsize  is  the  ini  size 
of  g_lvector  in  bytes. 

WHEN  ASSIGNED:  Changes  the  element  of  gjvector. 

SAT_YES  (<comment>)  IC  Macro) 

SAT_NO  (<comment>)  [C  Macro) 

SATJEXCEPTION  (<comment>)  [C  Macro] 

WHERE:  <comment>  is  any  C  macro  argument  (e.g.,  it  must  not  contain  commas  out¬ 
side  parentheses). 

VALUES:  SAT^YES  (<comment>)  equals  1,  SAT_NO  (<comment>)  equals  0,  and 
SATJEXCEPTION  (<comment>)  equ7i\s  -I .  The  <comment>  is  ignored. 


uchar 

EQUIVALENT  TO:  Unsigned  char. 

ulong 

EQUIVALENT  TO:  Unsigned  long. 

ushort 

EQUIVALENT  TO:  Unsigned  short. 


[C  Type] 


[C  Type] 


[C  Type 


x_  [Argument  Prefix] 

ux_  [Argument  Prefix] 

DENOTATION:  In  C,  denotes  arguments  of  int  or  unsigned  int  {unsigned)  type.  In  LISP, 
denotes  arguments  of  fixnum  type. 
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1.  OBJECTS.  A  SKETCH  object  has  a  type  and  a  list  of  attributes.  Each  attribute 
has  a  label  and  a  value.  The  types  of  SKETCH  objects  have  names  beginning  with  ‘a-*  or 
‘an-’.  The  attribute  labels  of  SKETCH  objects  have  names  beginning  with  ‘has-’  or  ‘is-', 
or,  in  general,  with  any  auxiliary  verb  or  preposition  followed  by  a  hyphen. 

A  SKETCH  object  may  be  represented  by  an  expression  that  evaluates  to  the  object, 
such  as— 

(a-man  has-weight  174  has-height  70). 

The  ‘a-man’  macro  called  by  this  expression  is  the  same  as  the  name  of  the  object  type, 
and  the  argument  list  consists  of  attribute  label/value  pairs,  with  each  Inbel  (e.g.  ‘has- 
weight’)  followed  by  its  value  (e.g.  ‘174’). 

SKETCH  types  are  themselves  SKETCH  objects  whose  type  is  the  SKETCH  type 
a-type.  SKETCH  attribute  labels  are  themselves  SKETCH  oi)jects  whose  type  is  the 
SKETCH  type  an-attribute.  Thus  the  existence  of  the  above  object  implies  the  existence 
of  other  objects  such  as— 

{a-type  has-iiaine  'a-man  ...) 

(a7i-a//ri6u/e  lias-name  ’has-weight) 

{an-attribiite  has-naine  ’has-height) 
and  these  in  turn  imply  the  existence  of— 

{a-type  has-name  ’a-type  ...) 

{a-type  has-naine  ’an-attribute  ...) 

(an-a//rj6ti/c  has-naine  ’has-name). 

2.  MAKING  OBJECTS.  A  SKETCH  object  can  be  made  by  evaluating  an  expres¬ 
sion  that  represents  it,  such  as— 

(a-man  has-weight  174  has-height  70). 

Symbols  naming  the  type  and  attribute  labels  are  used  in  this  expression,  along  with  the 
values  of  the  attributes.  In  this  expression,  all  the  attribute  labels  and  values  are 
evaluated,  so  that  the  expression  gives  the  same  result  as— 

(a-man  has-weight  {plus  100  74)  has-height  {difference  72  2)). 

Use  is  made  of  the  facts  that  the  symbol  ‘a-man’  is  defined  as  a  macro  which  creates 
objects  of  type  ‘a-man’,  and  that  the  symbols  ‘has-weight’  and  ‘has-height’  evaluate  to 
an-attribute  SKETCH  objects  that  serve  as  attribute  labels. 
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The  object  that  results  from  evaluating  one  of  these  expressions  can  be  houiul  to  a 
variable,  as  in— 

(sc/7  george  (^t-man  has-weight  17-^  has-height  70)). 

This  actually  stores  a  pointer  to  the  a-man  object  in  the  variable  george,  and  we  will 
describe  in  more  detail  what  this  means  at  the  end  of  the  next  section. 

It  is  also  possible  to  use  one  object  as  a  prototype  to  supply  default  values  for  the 
attributes  of  a  new  object.  Writing— 

(a-man  george  has-weight  169  has-age  57) 
uses  george  as  such  a  prototype,  and  makes  the  object  represented  by— 

(a-man  has-weight  169  has-age  57  has-height  70). 

The  prototype,  if  present,  is  the  first  thing  after  the  type,  a-inan.  in  the  expre.s.'^ioii  mak¬ 
ing  the  new  object. 

3.  GETTING  AND  SETTING  ATTRIBUTES.  Attributes  can  be  gotten  by 
expressions  such  as— 

(has-weight  george), 

which,  given  the  above  definition  of  george,  has  the  value  '\7  \\  or— 

(has-height  george), 

which  has  the  value  ^70\  The  type  of  an  object  can  be  gotten  as  if  it  were  the  object^s 
has-type  attribute,  via— 

[has-type  george), 

which  has  the  value— 

[a-type  has-name  ’a-man  ...). 

Objects  with  has-name  attributes  often  print  as  just  their  names,  so  if  you  print  out  this 
last  object  you  may  get  just  ‘a-man’. 

The  LISP  self  macro  can  be  used  to  change  attributes,  as  in  — 

(sc//(has-weight  george)  185), 
after  which  george  will  equal— 

(a-man  has-weight  185  has-height  70) 

New  attributes  can  be  defined  for  an  object,  as  in— 

(5c//(has-age  george)  34), 

after  which  george  will  equal— 

(a-man  has-weight  185  has-height  70  has-age  34). 

If  an  attempt  is  made  to  get  an  attribute  that  an  object  does  not  have,  nil  will  be 
returned,  as  in— 

(has-waist-size  george). 

This  is  not  an  error.  Setting  an  attribute  to  the  value  nil  genernlly  makes  the  attribute 
disappear  (‘generally’  means  that  exceptions  are  rare,  and  noted  in  documentation).  Thus 
after— 
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(^je//(has-weight  george)  nil) 

george  will  equal— 

(a-man  has-height  70  has- age  34). 

In  general,  saying  that  an  object  does  not  have  an  attribute,  and  saying  that  it  has 
the  attribute  value  nzV,  are  two  ways  of  saying  the  same  thing. 

If  the  attribute  to  be  gotten  is  not  known  till  eval  time,  the  get-attribute  function 
may  be  used  to  get  the  attribute.  Examples  are— 

{setq  X  {an-attribute  /las-riame  *has-height)) 

{get-attribute  x  george), 

in  which  the  second  expression  evaluates  to  70,  and— 

{set/ [get-attribute  .\  george)  85), 

which  changes  george  to— 

(a-man  has-height  85  has-age  34) 

In  the  above  examples,  george  is  just  a  variable  that  is  always  evaluated.  If  one  had 
executed— 

(setq  y  george) 

first,  one  could  use  y  and  george  interchangeably  above. 

When  two  variables,  such  as  y  and  george,  are  both  bound  to  the  same  oi)ject,  they 
in  fact  both  contain  equal  pointers  to  the  object.  Any  change  to  the  object  will  appear  to 
effect  both  variables.  Thus  if  george  equals— 

(a-man  has-height  85  has-age  34), 

so  will  y,  and  after— 

[seif  (has-age  y)  35), 

both  y  and  george  will  equal— 

(a-man  has-height  85  has-age  35). 

The  type  of  an  object  cannot  be  changed: 

(set/ [has- type  george)  ...) 

is  in  error. 

4.  NAMES.  If  an  object  has  a  has-name  attribute  that  has  a  non-rn/  value,  that  value 
must  be  a  symbol,  and  that  symbol  will  be  set  equal  to  the  object.  For  example,  evalua¬ 
tion  of  the  expression— 

(a-man  has-name  ’Bill  has-weight  143  has-height  68) 
will  make  an  object  and  set  the  variable  Bill  equal  to  that  object. 

When  the  print  function  is  asked  to  print  an  object  with  a  /las-name  attribute,  the 
value  of  this  attribute  will  be  printed  as  the  complete  representation  of  the  object.  Thus 

[print  Bill) 

will  print  just  ‘Bill’.  Other  forms  of  printing  objects  with  has-name  attributes  are 
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available,  and  are  described  below  (see  PRINTING  AND  UNEVALUATING  OBJECTS). 

After  an  object  with  a  name  is  made,  it  can  be  referenced  by  an  expression  that 
appears  to  make  a  new  object  with  the  same  has-name  but  no  other  attributes.  In  this 
case,  evaluating  the  expression— 

(a-man  has-name  ’Bill) 

will  not  make  a  new  object,  but  will  instead  return  the  already  made  object  that  is  the 
value  of  the  variable  Bill. 

An  object  that  has  a  type  and  a  has-name  attribute,  but  has  no  other  non-ni7  attri¬ 
butes,  is  called  a  stub.  In  general,  an  attempt  to  make  a  stub  for  an  object  that  already 
exists  will  not  make  a  new  object,  but  will  merely  return  the  existing  object. 

The  order  of  making  stubs  and  objects  can  be  reversed.  If  the  stub  is  made  first,  an 
attempt  to  make  the  object  will  not  make  a  new  object.  Instead,  it  will  fill  in  the  attri¬ 
butes  of  the  stub,  and  return  that  stub,  which  will  no  longer  be  a  stub  any  more.  Thus 
the  code— 

(a-man  has-name  ’Bill  has-wife  (a-woman  has-name  ’Jill)) 

(a- woman  has-name  ’Jill  has-husband  (a-man  has-namc  ’Bill)) 

will  work,  making  only  two  objects,  and  setting  the  variables  Bill  and  Jill.  This  code 
would  give  the  same  result  if  we  reversed  the  order  of  its  two  statements.  The  value  of— 

(has-wife  Bill) 

is  the  same  as  the  value  of  the  variable  Jill,  while  the  value  of— 

(has-husband  Jill) 

is  the  same  as  the  value  of  the  variable  Bill. 

If  an  object  with  a  has-name  is  to  be  made,  and  another  object  with  the  same  name 
exists  before  hand,  and  if  neither  object  is  a  stub,  then  the  two  objects  are  tested  for 
equality  of  their  attributes  (using  the  compare- object  function  that  ignores  hidden  attri¬ 
butes:  see  the  GLOSSARY).  If  there  is  equality,  a  new  object  is  not  made,  and  the  old 
object  is  returned  as  the  result  of  the  expression  that  might  have  made  the  new  object.  If 
there  is  no  equality,  an  error  is  signaled.  Thus  a  named  object  may  be  made  many  times 
if  it  is  always  made  the  same  way. 

The  notion  of  a  name  may  be  generalized  to  use  attributes  other  than  has-name  to 
denote  an  object.  Such  generalized  naming  is  referred  to  as  ‘indexing’,  and  is  discussed 
later  in  more  detail.  Indexing  also  includes  placing  objects  on  hidden  cross-reference  lists 
that  may  be  used  to  retrieve  the  object. 

We  have  discussed  ‘making’  objects  in  SKETCH,  and  not  ‘creating’  them.  In 
SKETCH,  ‘creating’  an  object  is  a  suboperation  of  ‘making’  the  object,  and  does  not 
include  any  indexing. 

5,  DYNAMIC  TYPE  AND  ATTRIBUTE  CREATION-  New  types  and  attributes 
can  be  created  by  expressions  such  as— 
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{a-type  lias-name  *a-man) 

[an-attribute  has-name  ’has- weight.) 

{an-attribute  has-namc  ’has-height) 

[an-attribute  luis-Jiaine  ’has-age). 

However,  types  and  attributes  mentioned  in  data  and  interpreted  code,  but  not  in  com¬ 
piled  code,  need  not  be  created  before  they  are  used.  Instead,  they  may  be  given  names 
that  begin  with  one  of  several  specific  prefixes,  in  which  case  they  will  be  created 
automatically  when  they  are  used. 

For  types,  the  prefixes  are  a-  and  an-.  For  attributes,  the  standard  prefixes  are  has-, 
IS-,  and  isnt-,  and  any  auxiliary  verb  or  preposition  followed  by  a  hyphen  may  be  added 
to  this  list  as  needed  (see  define-objeci-navi e-pr efix  in  the  GLOSSARY). 

For  example,  evaluating— 

(a-man  has-name  ’George  has-age  53  has-wife  (a-\voman  has-name  ’Jill)) 

when  a-man,  has-age,  has-wife,  and  a-woman  are  unbound  variables  will  automatically 
cause  the  expressions— 

[a-type  has-name  ’a-man) 

[mi-attribute  has-name  ’has-age) 

[an-attribute  has-naine  ’has-wife) 

[a-type  has-name  ’a-woman) 

to  be  evaluated. 

Thus  data  bases  stored  in  files  may  use  types  and  attributes  previously  unknown  to 
the  program. 

Types  and  attributes  explicitly  mentioned  in  compiled  code,  however,  should  be 
made  before  they  are  used.  This  may  be  done  by  executing  expressions  such  as— 

[eval-when  [compile  load  eval) 

[a-type  has-name  ’a-man) 

[an-attribute  has-name  ’has-age) 

[an-attribute  has-name  ’has-wife) 

[a-type  has-name  ’a-woman)). 

The  eval-when  is  necessary  to  ensure  that  the  types  and  attributes  are  created  both  in  the 
compiler  and  at  eval  time. 

If  an  object  with  a  non- mV  has-name  attribute  is  made  in  the  compiler  environment, 
the  name  of  that  object  will  automatically  be  declared  to  be  special,  thus  permitting 
reference  to  it  in  code.  Objects  made  in  the  compiler  environment  should  also  be  made  in 
the  evaluation  environment,  so  the  code  will  reference  the  right  object.  The  eval-when 
[compile  load  eval)  in  the  above  example  does  just  this. 

Often  the  declare-hunk-type  or  declare-vector-type  macros  described  in  the  next  sec¬ 
tion  are  used  to  create  types  and  attributes,  instead  of  the  more  direct  methods  just 
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described. 


6.  BASIC  TYPES.  In  SKETCH  one  builds  types  on  top  of  one  another.  Generally, 
one  starts  with  a  basic  type  that  is  made  by  an  expression  such  as— 

[declarc-hunk-type  an-event 

ha$-pa$$word  *event-password* 

has-name  has-st art- time 

is-read-init’privatc 

has-stop-time 

is- hidden  is- private 

has-previous-event). 

Declare-hnnk-type  is  a  macro  whose  arguments  are  generally  not  evaluated  (like  declare). 
However,  there  is  a-  similar  function,  define- hu7ik- type,  whose  arguments  are  evaluated. 
Both  the  macro  and  the  function  make  one  a-type  object  with  the  given  name  (e.g.  an- 
event),  and  several  an-attribute  objects  with  given  names  (e.g.  has-name,  luis-start-time, 
has-stop-time,  and  has-previous-event). 

An-attribiUe-descriptor  objects  are  also  created  for  each  attribute  label,  and  an- 
operalion-descriptor  objects  are  made  for  each  operation  (e.g.  make-object^  object-is^ 
uneval- object,  format-object)  that  is  to  be  defined  in  a  type  specific  manner.  See  the  sec¬ 
tions  below  and  the  GLOSSARY  for  details  of  making  these  objects. 

The  above  call  defines  a  new  type:  an-event.  The  attributes  of  this  type  that  are 
known  to  the  compiler  are— 

has-name  has-start-time  has-stop-time  has-previous-event. 

These  attributes  are  packed  into  objects  of  the  new  type,  and  are  efficiently  accessed  (the 
objects  are  actually  hunks,  and  the  access  is  by  indexing  elements  of  the  hunks).  Other 
attributes  may  be  set  and  gotten  for  an-event  object,  but  these  will  be  stored  in  a  pro¬ 
perty  list  where  their  access  will  be  slower. 

By  default,  attributes  can  be  initialized  and  read,  but  not  written  (i.e.  not  self).  The 
is-read-init-private  keyword  signifies  that  subsequent  attributes  can  also  be  written  if  the 
password,  in  this  case  the  symbol  *event-password*,  is  included,  as  in— 

(5ClI/(has-stop-time  x  *event-password*)  y). 

VVe  will  use  the  fact  that  has-stop-time  can  be  written  with  a  password  in  the  section  on 
THE  FORMAT-OBJECT  OPERATION  below. 

The  is-private  keyword  signifies  that  subsequent  attributes  cannot  be  initialized,  but 
can  be  read  or  written  if  the  password  is  include,  as  in— 

(has-previous-event  x  *event-password*) 

and— 


(5c/!/(has-previous-event  x  *event- password*)  y). 


Assuming  that  code  in  one  program  package  does  not  use  the  password  of  another 
package,  a  private  attribute  may  be  protected  from  incorrect  access  by  code  outside  the 
package  that  defined  the  attribute. 

Other  keywords  that  play  a  role  similar  to  is-read-init-privale  and  is-private  are  is- 
read-initj  which  is  the  default  and  disallows  writing  the  attribute  but  allows  reading  and 
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initializing  it;  t$-read~uiit- write  which  allows  reading,  initializing,  and  writing;  and  rs- 
read‘privaie  which  allows  reading  but  not  initializing,  and  allows  writing,  but  only  with  a 
password. 

By  default,  attributes  are  printed  out  when  the  object  is  printed,  and  are  included  in 
the  result  of  unevaluating  the  object  (see  PRINTING  AND  UNEVALUATING  OBJECTS 
below).  The  is-hiddtn  keyword  signifies  that  subsequent  attributes  are  not  to  be  printed 
or  appear  in  the  unevaluated  object.  Such  hidden  attributes  are  often  used  for  cross- 
reference  lists  between  objects.  These  cross-reference  lists  can  be  very  bulky  to  print,  and 
should  not  be  transmitted  between  different  memory  loads  (which  is  the  purpose  of 
unevaluated  objects). 

Hidden  attributes  are  also  ignored  when  testing  two  objects  for  equality,  as  is  done 
when  two  objects  with  the  same  name  are  made  (see  NAMES  above,  and  compare-object 
in  the  GLOSSARY): 

The  is-visible  keyword  is  the  opposite  of  i$-hidden.  and  signifies  that  subsequent 
attributes  are  to  be  printed,  appear  in  the  unevaluated  object,  and  be  considered  during 
tests  for  object  equality.  In  the  OTHER  ATTRIBUTE  SWITCHES  section  below,  we 
describe  how  an  attribute  can  be  made  hidden  in  some  ways  and  visible  in  others. 

The  declare-vector-iype  macro  is  similar  to  dec! are-hunk- type  but  defines  objects 
that  are  LISP  immediate  vectors  (see  the  FRANZ  LISP  manual)  and  C  structures  A  typ¬ 
ical  use  might  be— 

(declare-vector-type  an-event 

has-password  *event-password* 

a-value  lias-name 

a-long  has-start-time 

is-read-init-private 

a-long  has-stop-time 

is-hidden  is-private 

a-value  has-previous-event). 

In  a  declare-vector-type  call,  the  data  type  of  the  attributes  can  be  declared  to  be  be  a  C 
numeric  type,  such  as  char,  long,  or  float,  rather  than  just  a  LISP  value.  This  is  done  by 
including  type  names  such  as  a-char,  a-long,  and  a-float  in  front  of  the  attribute  labels  for 
the  attributes  that  are  to  have  the  given  type.  The  type  name  a-value  refers  to  LISP 
values,  and  is  the  default  at  the  beginning  of  the  attribute  list.  The  first  element  of  the 
vector  stores  the  type  of  the  object,  as  a  LISP  value.  The  property  list  of  the  vector  (see 
the  FRANZ  LISP  manual)  is  a  hunk  that  stores  a  copy  of  all  the  LISP  values  stored  in 
the  vector,  so  that  the  garbage  collector  will  know  about  these  values. 

Both  declar e-hunk- type  and  declare-vector-type  expand  into  an— 

{eval  {compile  load  eval)  ...) 

form,  so  they  will  be  effective  at  all  times.  If  appropriate  extra  arguments  are  given  to 
these  macros,  and  if  the  global  variable  *C-deflnition-port*  is  set  to  a  port  when  either  of 
these  macros  is  called  (e.g.  loaded  or  compiled),  then  C  structure  definitions  are  written 
into  this  port  so  that  C  code  can  access  the  information  in  the  object. 

For  example,  the  declaration— 
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[declare-veclor-lype  (aii-evenl  ev_event.  ev_) 
lias-password  *event* password* 
a-vahie  (hixs-name  nil  ev_name) 
a-Jloal  (has-st-art-tinie  nil  ev_start) 

15-  read-  m  i  I- p  ri  m  t  e 

a-float  (has-stop-time  nil  ev_stop) 

is-hidden  is-privale 

an-event  (has-previous-event  nil  ev.previous)) 
will  output  the  C  structure  definitions— 

lypedef  struct  ev_struct  *  ev.event; 
struct  ev_3truct  { 

union  {int  SOB_VSIZE  [l]; 

sat^lcolue  *  SOB_^  PLIST  -l]; 
sobjype  SOB_VT^*PE;  }  sbB.VFIRST; 

#  deyJ/ieev^ypeSOB.VFIRST.SOB.VTYPE 

#  define  ev^plist  SOB_VFIRST.SOB_VPLISTl-ll[0] 

#  define  ev_vsize  SOB_VFIRST.SOB_VSIZE[-2] 

S(it_lvalue  ev_iiame; 

float  ev_start ; 
float  ev_stop: 
ev_event  ev_previous; 

}; 

if  define  ev_alIoc(x,y)  struct  ev_struct  (x)  [y] 

See  the  GLOSSARY  entries  on  declare-hunk-type  and  declare-vector-type  for  tnore 
information. 


7.  CHECKING  TYPES.  It  is  often  necessary  to  check  whether  an  object  is  of  a  par¬ 
ticular  type.  This  can  be  most  efficiently  done  by  the  object-i$  function,  as  in  — 

{object-is  an-event  x), 

which  evaluates  to  non-nil  if  x  is  an-event.  If  it  is  necessary  to  discover  the  type  of  an 
object,  this  may  be  done  less  efficiently  by  the  has-type  function,  as  in— 

{lias-type  x), 


which  evaluates  to— 


if  X  is  an-event. 


{a-type  lias-nanie  an-event  ...) 


8.  PRINTING  AND  UNEVALUATING  OBJECTS.  Printing  objects  is  best  done 
by  the  pretty-print  function,  as  in  — 

(prc//y-prin/  x). 

This  function  contrives  to  insert  line  feeds  as  necessary  to  make  the  object  fit  within  lines. 
No  part  of  the  object  is  to  the  left  of  the  initial  print  position,  and  every  attribute  value 
is  indented  with  respect  to  its  label.  The  number  of  line  feeds  inserted  is  returned  by  this 
function. 
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If  an  object  x  has  an  attribute  with  value  y,  and  if  y  has  a  lias-nanfe  allribute  with 
value  z,  then  when  x  is  pretty-prinfed,  z  will  be  printed  in  place  of  y.  Thus  y  is 
represented  by  its  name.  However,  this  will  not  be  done  for  x  itself,  which  will  always  be 
printed  as  a  type  and  list  of  attributes. 

The  top  level  printer  uses  pretty-print  to  print  evaluation  results,  unless  a  result  has 
a  non- nil  has-name  attribute  value  which  is  not  identical  to  the  expression  evaluated  to 
get  the  result,  in  which  case  just  the  has-namc  value  is  printed.  Thus  after  evaluating— 

(a-man  has-namt  ’Bill  has-wife  (a-woman  has-name  ’Jill)) 

(a-woman  has-name  ’Jill  has-husband  (a-man  lias-name  ’Bill)), 

evaluating  ‘Bill’  at  the  top  level  prints— 

(a-man  has-name  ’Bill  has-wife  Jill). 

while  evaluating— 

(has-husband  Jill) 

prints  just  ‘Bill’. 

One  cannot  copy  the  printed  representation  of  an  object  into  a  file,  read  back  the 
file,  and  get  the  object  again.  This  sort  of  thing  can  be  done  for  some  LISP  values,  but 
not  fer  '^KETCH  objects.  However,  the  nveval-ohjecf  fuiicnon  will  trnnsforin  any 
SKETCH  object  into  a  LISP  object  that  has  this  print-re-read  abilrty.  and  which,  when 
evaluated,  will  yield  the  SKETCH  object.  Thus  the  code— 

(setq  y  {nneval-object  x)) 

[pretty-print  y  some-output-port) 

[setq  z  [read  corresponding-input-port)) 

[setq  w  [eval  z)) 

will  generally  cause  w  to  equal  x  (and  z  to  equal  y). 

Here,  also,  if  some  attribute  value  of  x  is  an  object  with  a  has-name  attribute,  that 
attribute  of  x  will  be  represented  in  y  by  just  its  type  and  name,  as  in- 

(a-man  has-name  ’Bill). 

So  an  equal  object  of  the  same  name  must  be  made  to  exist  in  the  environment  that 
evaluates  z.  However,  x  itself  will  not  be  represented  by  its  name,  if  it  has  one,  but  will 
always  be  represented  as  a  type  and  list  of  attributes. 

Thus  the  unevaluation  of  ‘Bill’  above  is— 

(a-man  has-name  ’Bill  has-wife  (a-woman  has-name  ’Jill)), 
while  the  unevaluation  of  ‘Jill’  is— 

(a-woman  has-name  ’Jill  has-husband  (a-man  has-name  ’Bill)). 

9*  OPERATIONS.  Operations  can  be  defined  which  are  like  functions  that  have 
different  definitions  depending  upon  the  type  of  their  first  argument.  Operations  can  also 
have  both  a  macro  definition,  used  at  macro  expansion  time  if  the  type  of  the  first  argu¬ 
ment  can  be  deduced  at  that  time,  and  a  function  definition,  used  at  evaluation  time,  if 
the  type  of  the  first  argument  is  not  known  at  macro  expansion  time. 

To  define  an  operation  called  *’move-forward**  we  write— 
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{eval-when  [eval  load  compile) 

[amoperalion  has-name  'move-forward)). 

To  define  how  it.  will  be  applied  to  an-event  object  we  write— 

[eval*when  [eval  load  compile) 

{an- operation- descriptor  has-naine  ’*move-event-forward-descriptor* 

lias-type  an-event 

has-operation  move-forward 

has- function  ^move-event- for  ward- function 

has-macro  ’move-event-forvvard-macro 

lias-parameters  <some-parameter > )). 

Now  the  call— 

(move-forward  \  y) 

were  x  is  an-event  will  evaluate  the  same  as— 

[funcall  ’move-event-forward-fimction 

*  move-event- forward-descrip  tor*  move- Forward 
X  y). 

Move-event-forward-function  can  access  the  has-parameters  attribute  oF  *move-event- 
forward-descriptor*  if  it  wants  to.  This  can  allow  one  function  to  serve  for  several 
related  operations. 

Move-event-forward-function  will  be  used  instead  oF  move-event-Forward-inacro 
because  the  type  of  x  is  not  known  at  macro  expansion  time.  However,  the  call— 

(move-forward  (an-event  x)  y) 

will  be  macro  expanded  to— 

(move-event- forward-macro  7^.  *move-event- forward- descrip  tor*  ^.move-event 

(an-event  x)  y) 

which  will  expand  in  turn.  Note  that  the  first  two  arguments  are  not  expressions,  but 
rather  an-operation- descriptor  ob}ect  and  an- operatio n  oh}ect  (the  instructs  the  LISP 
reader  to  both  read  and  evaluate  the  next  expression,  and  return  the  result  of  the  evalua¬ 
tion  as  the  thing  read).  The  has-parameters  attribute  of  the  former  could  be  accessed  by 
move-event-forward-macro. 

Macro  arguments  like  the  first  two  to  move-event-forward-macro  are  called  *pre- 
evaluated’.  Such  arguments  are  actual  values,  rather  than  expressions  which  evaluate  to 
values  at  some  later  time.  Pre-evaluated  macro  arguments  provide  parametric  informa¬ 
tion  to  macros  efficiently.  However,  pre-evaluated  arguments  must  not  be  used  in  the 
expansion  of  the  macro,  unless  the  macro  expands  to  a  call  on  another  macro  that  also 
accepts  pre-evaluated  arguments. 

If  move-event-forward-macro  were  not  given  (the  has-macro  attribute  of  *move- 
event-forward-descriptor*  was  omitted),  then  — 

(move-forward  (an-event  x)  y) 
would  be  macro  expanded  to— 

(move-event- forward- function  *move-event-forward-descriptor*  move-event 

(an-event  x)  y). 

Omitting  move-event-forward-function  (the  has-Jiinction  attribute  of  *move-event- 
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forward-descriptor’*'),  is  not  permitted. 

By  defining  another  operation  descriptor,  such  as— 

{evat-when  {eval  load  compile) 

(an’Operatioti’descriptor  has- name  ’*move- truck- forward-descriptor* 

has-type  a-truck 

has- operation  move-forward 

has-f unction  ^move-truck-forward-fu notion 

has-tnacro  ’move-truck-forward-macro 

lias-parameters  <some-parameter  >)), 

the  move-forward  operation  could  be  defined  differently  on  events  and  trucks. 


10.  PARENT  OPERATIONS.  It  is  possible  to  redefine  an  operation  in  such  a  way 
that  the  new  definition  uses  the  old  definition.  Suppose  we  have  defined  the  move-forward 
operation  as  above,  and  write— 

{eval-when  [eval  load  compile) 

(an- operation- descriptor  has-najne  '*newer-move-event-forward-desc!*iptoi  * 

has-type  an-event 
has-operation  move-forward 

has-fiinction  ‘newer- move-event-forward-function 
has- macro  ’newer-move-event-forward-macro 
has-parameters  <some-parameter > )). 

Now  the  call— 


(move-forward  .v  y) 

were  x  is  an-event  will  evaluate  the  same  as— 


(funcall  ’newer- move-event- for  ward- function 

*  newer- move- event- forward-descriptor*  move-forward 

xy) 


However  the  previous  definition  of  move-forward  has  not  been  lost.  Whenever  an- 
operation- descriptor  with  particular  has- descrip  tor  •  type  and  has- descriptor- operation 
attributes  is  made,  the  most  recently  made  operation  descriptor  with  the  same  has- 
descriptor-type  and  has- descriptor- op eration^  if  any,  becomes  the  parent  of  the  new 
descriptor.  In  our  case,  the  parent  operation  can  be  executed  by  the  call— 

(execute- parent-operation  *  newer- move-event- forward-descriptor* 

move-forward  x  y), 

which  will  evaluate  the  same  as— 

(funcall  ’move-event-forward-function 

*mov e-even t-forward-descriptor*  move- forward 
X  y). 


Similarly  the  call  — 


(execute- parent-operation  *  newer-move-even  t-forward-descriptor 

move-forward  (an-event  \)  y) 


will  macro  expand  to— 
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(move-event- forward- macro  #.* move-event-forward-descriptor*  ^.move-forward 

(an-event  x)  y). 

There  can  be  a  problems  with  reloading  a  code  file  into  an  environment  into  which 
the  file  has  previously  been  loaded,  such  as  after  fixing  bugs  in  the  file  during  debugging, 
if  the  file  contains  attribute  descriptor  definitions  such  as  that  in  the  eval-when  above. 
Normally,  any  newly  made  descriptor  is  added  to  all  the  previously  existing  descriptors, 
so  the  new  version  of  the  descriptor  and  the  old  version  would  both  be  active,  with  the 
old  version  being  an  ancestor  of  the  new.  However,  if  the  descriptor  has  a  has-narnc  attri¬ 
bute,  remaking  it  will  merely  return  the  old  descriptor  in  place  of  the  new  descriptor, 
without  making  any  new  active  descriptor.  This  is  what  should  happen,  so  descriptors 
should  be  named.  They  are  usually  named  anyway,  to  facilitate  their  use  in  execute- 
parent- operation  calls. 

But  now  a  different  problem  appears:  the  reloaded  descriptor  must  be  identical  with 
the  previously  loaded  descriptor  to  prevent  an  error  (see  NAMES  above).  Thus  one  can¬ 
not  fix  a  bug  in  the  descriptor  definition  without  reloading  from  scratch. 

11.  CREATE-OBJECT  OPERATIONS.  Often  the  creation  of  an  object  of  a  par¬ 
ticular  type  should  be  accompanied  by  checks  on  the  attribute  values  of  the  object.  These 
may  be  performed  by  a  special  create  function  for  the  object. 

First  note  that  the  create- object  opei?X\oi\  is  invoked  by  calls  such  as— 

[create- object  [list  an-event  has-start-time  1100 
has-stop-time  1330) 
nit) 

in  which  the  first  argument  is  a  list  which  represents  the  object,  and  the  second  argument 
is  a  prototype  object,  which  is  missing  (i.e.  nit)  in  this  case.  The  list  which  represents  the 
object  is  called  an  ^abnormal  object’.  It  has  the  object  type  as  its  first  element,  and  the 
object’s  attribute  label/value  pairs  as  its  remaining  elements.  The  prototype  object,  were 
it  present,  would  be  used  to  supply  default  values  for  attributes  not  specified  in  the 
abnormal  object. 

Now  given  the  declare-hunk-type'def\mt\on  of  an-event  above,  we  may  evaluate— 

[eval-when  [compile  load  evat) 

[an- operation- descriptor 
has-name  ’*create-event-descriptor* 
has- descriptor- operation  create- object 
has- descriptor- type  an-event 
has-function  ’create-event)), 

and  thereby  introduce  a  new  function,  create-event,  to  take  over  the  job  of  creating  an- 
event  objects.  This  function  might  be  written  as— 
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{defun  create-event  (the-operation-descriptor  the-operotion 

the^objcct  the-prototype 
&aux  the-event) 

{setq  the-event  {create-pareni-object  *create-event-descriptor* 

the-object  the-prototype)) 

{co7\d  {[not  {object-is-a‘Stub  (an-event  the-event))) 

{assert  {fixp  (has-start-time  (an-event  the-event))) 

*(has-start-time  attribute  is  not  a  fixnum)) 

{assert  {fixp  (has-stop-time  (an-event  the-event))) 

’(has-stop-time  attribute  is  not  a  fixnum)) 

(a55eri  {not  {lessp  (has-stop-time  (an-event  the-event)) 

(has-start-time  (an-event  the-event)))) 

’(has-stop-time  attribute  is  less  than  has-start-time  attribute)))) 

the-event). 

This  function  first  uses  the  object  creation  facility  provided  by  the  parent  descriptor 
of  *create-event-descriptor*:  that  is,  by  the  descriptor  for  the  create-objeci  operation  on 
an-event  type  objects  that  existed  just  before  *create-event-descriptor*  was  made.  This 
parent  is  invoked  by  the  call— 

{create-parent-object  *create-event-descriptor*  the-object  rhe-prototype), 
which  is  almost  equivalent  to— 

{execute-parent- operation  *create-event-descriptor*  create-object 

the-object  the-prototype), 

but  differs  in  that  it  does  not  try  to  extract  the  type  of  the-object  by  executing— 

{has-type  the-object), 

but  uses— 

{first  the-object) 

instead,  because  the-object  is  not  an-event  object,  but  rather  an  abnormal  object. 

Our  function  then  checks  the  attribute  values,  and  returns  the  object  created.  We 
must  not  check  the  attributes  in  the  case  when  the  object  created  is  a  stub  (see  NAMES 
above). 

Note  that  we  write  ‘(an-event  the-event)’  instead  of  simply  ‘the-event’  whenever  we 
reference  an  attribute  of  the-event.  The  compiler  uses  the  extra  information  that  the- 
event  is  an-event  to  compile  much  more  efficient  code  for  accessing  the  event.  In  fact,  the 
code  that  is  compiled  for  element  references  executes  in  about  1  microsecond  in  this  case, 
whereas  if  the  information  is  omitted  the  compiled  code  might  take  more  than  100 
microseconds. 

12.  MAKE-OBJECT  OPERATIONS  AND  INDEXING.  The  act  of  making  an 
object  is  different  from  creating  it.  Making  an  object  first  creates  it,  and  then  indexes  it. 
We  can  add  a  make  function  special  to  an-event  by  writing— 
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(eval-when  {compile  load  eval) 

( (ux-operaiion-descriptor 
has-name  make-even t-clescriptor* 
liQS-descriptor’operation  make-object 
lias-descriptor-type  an-event 
has-function  ’make-event)) 

to  introduce  the  new  function  make-event  for  making  an-event  objects.  The  make-event 
function  could  be  defined  as  follows— 

(dejvar  *event-list*)  ;  List  of  all  events  sorted  by  has-start-time. 


{defun  make-event  (the-operation-descriptor  the-operation 

the-object  the-prototype 
&(tux  the-eveiu) 

{setq  the-event  {make-pareixt-object  *make-event-cle5criptor^ 

the-object  the-prototype)) 

{cond  ((no/ (has-start-time  (an-event  the-event)))) 

((or  {null  *event-list*) 

{lessp 

(has-start-time  (an-evenr  the-event)) 

(has-start-time  (an-event  {first  *evenL-list*))))) 

{push  the-event  *event-list*)) 

(« 

(do  ((the-list  *event-list*  {resfl  the-list))) 

{{or  {null  {rest  1  the-list)) 

{lessp 

(has-start-time  (an-event  the-event)) 

(has-start-time  (an-event  {second  the-list))))) 
(sc/!/(has-previous-event  the-event  *event-pass\vord*) 

{first  the-list)) 

{if{re$tl  the-list) 

(se//(has-previous-event  {second  the-list) 

*event-pass\vord*) 

the-event)) 

{setf{restl  the-list) 

‘(, the-event  .  ,{restl  the-list))))))) 

the-event). 

This  function  first  uses  the  object  making  facility  provided  by  the  parent  descriptor  of 
*make-event-descriptor*.  This  facility  is  invoked  by  the  call  to  make-parent-object  \w\\\ch 
behaves  like  create-parent-object  (see  last  section:  the-object  is  an  abnormal  object  here 
too).  Our  function  then  indexes  the  new  event,  by  setting  its  has-previous-event  attribute 
to  the  nearest  previous  event,  if  any,  and  by  ptis/i’ing  it  into  the  *event-list*.  However, 
this  indexing  is  not  done  if  the  newly  created  event  is  a  stub,  which  would  be  true  if  and 
only  if  its  has-start-time  is  nil  (because  of  the  checks  made  by  the  create-event  function 
above). 


The  reason  why  the  has-previous-event  attribute  is  hidden  (see  the  section  above  on 
BASIC  TYPES)  should  now  be  clear.  If  the  has-previous-event  attribute  were  to  be 
printed  v/hen  an-event  object  is  printed,  its  value  would  be  another  event  object,  which 
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when  printed  would  contain  another  has-previous-event  attribute,  which  would  print  yet 
another  an-event  object,  and  so  on  recursively.  Also,  if  an-event  object  is  copied  from  one 
memory  load  to  another,  the  has-previous-event  list  in  the  target  memory  might  be 
different  from  that  in  the  source  memory.  So  the  has-previous-event  attribute  should  not 
be  copied,  but  should  be  recomputed  when  the  object  arrives  in  the  target  memory. 

13.  STANDARD  OPERATIONS.  Table  5.1  is  a  synopsis  of  all  the  operations  that 
are  known  to  the  object  system.  All  but  the  ones  that  index  descriptors  are  standardly 
defined  for  all  SKETCH  objects  by  declare- hunk- type,  declare-vector-type,  or  the 
SKETCH  dynamic  type  creation  mechanism  (see  BASIC  TYPES  and  DYNAMIC  TYPE 
AND  ATTRIBUTE  CREATION  above).  Compare-object  and  uneval-object  are  also 
defined  for  LISP  objects,  such  as  numbers  and  lists. 

14.  ATTRIBUTE  DESCRIPTORS.  There  are  a  number  of  diflereiu  operations 
associated  with  a  given  attribute  and  a  given  type— 

(1)  Get  the  value  of  the  attribute  from  an  object  of  the  given 
type. 

(2)  .'^et  the  value  of  the  attribute  for  an  object  of  the  given 
type. 

(3)  Inspect  and  optionally  change  an  initial  value  of  the  attri¬ 
bute  for  an  object  of  the  given  type  which  is  being  made. 

(4)  Provide  the  default  value  of  the  attribute  for  an  object  of 
the  given  type  which  is  being  made. 

(5)  Determine  whether  the  attribute  is  to  appear  in  a  pretty- 
printed  version  of  an  object  of  the  given  type,  and  optional¬ 
ly  format  the  attribute  value  in  a  special  manner  when  it  is 
to  be  part  of  such  a  pretty-printing. 

(6)  Determine  whether  the  attribute  is  to  appear  in  an 
unevaluated  version  of  an  object  of  the  given  type,  and  op¬ 
tionally  unevaluate  the  attribute  value  in  a  special  manner 
when  it  is  to  be  part  of  such  an  unevaluation. 

(7)  Determine  whether  the  attribute’s  values  are  to  be  com¬ 
pared  when  objects  of  the  given  type  are  compared,  and  op¬ 
tionally  compare  the  attribute’s  values  in  a  special  manner 
when  such  objects  are  compared.’ 
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TABLE  5.1 

STANDARD  OBJECT  OPERATIONS 

make-object 

Makes  an  object.  First  applies  lias-mit-  functions 
and  macros  to  attribute  values  destined  for  the  ob¬ 
ject,  and  finds  default  values  for  attributes  not 
specified.  Then  creates  the  object,  and  lastly 
inde.ves  the  object. 

ere  ate- object 

Creates  an  object.  Does  no  indexing.  Does  not  use 
default  values  or  has-init-  functions  or  macros. 

object- is 

Tests  objects  to  see  if  they  are  of  a  given  type. 

object- is-a-stub 

Tests  objects  to  see  if  they  are  a  stub. 

compare-object 

Tests  objects  for  equality  of  all  non-hidden  attri¬ 
butes. 

move-object 

Sets  all  the  attributes  of  the  second  object  to  the 
values  of  the  attributes  of  the  first  object,  and  then 
discards  the  first  object  (it  cannot  be  further  used 
again). 

uneval-object 

For  an  object,  returns  a  LISP  object  that  will  evalu¬ 
ate  to  the  object,  and  which  can  be  printed  and  re¬ 
read  without  being  changed. 

format-object 

For  an  object,  returns  a  format  that  can  be  pretty- 
print- format' ed  to  pretty-print  the  object. 

index-operation-descriptor 

Records  the  existence  of  a  new  operation  descriptor 
for  a  type  (see  an-operation- descriptor  in  the  GLOS¬ 
SARY). 

index- attribute-descriptor 

Records  the  existence  of  a  new  attribute  descriptor 
for  a  type  (see  an- attribute- descriptor  in  the  GLOS¬ 
SARY). 

(8)  Determine  whether  the  attribute  value  is  to  be  tested  for  nil 
when  an  object  of  the  given  type  is  tested  to  see  if  it  is  a 
stub,  and  optionally  perform  this  test  in  a  special  manner 
when  such  an  object  is  tested. 

Rather  than  have  an- operatioii- descriptor  for  each  of  these  8  operations,  we  have 
an-attribute-descriptor  which  provides  information  for  all  8  operations.  The  attribute 
descriptor  in  turn  references  an-attribute-function-table  which  has  functions  and  macros 
for  the  first  3  of  the  above  operations.  Specifically,  the  attribute  function  table  has  the 
attributes— 
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bas-get-ftitfction  has-gct-inacro 
has-set-fnnction  ha^-set-tnacro 
liQS-imt-function  has- {nit- macro 

which  play  the  same  roles  as  the  has-fiwction  and  has-macro  attributes  of  an- operation- 
descriptor. 

For  the  fourth  operation  above,  default  value  specification,  the  attribute  descriptor 
does  not  provide  a  function  or  macro.  Instead  it  provides  an  expression  which  is 
evaluated  when  an  initial  value  is  needed. 

For  the  last  4  operations  the  attribute  descriptor  contains  a  switch,  which  behaves 
something  like  an-operation-descriptor  lias-fvnction  attribute.  The  switches  can  also  take 
the  values  yes  or  no,  whose  meaning  depends  upon  the  type  of  switch.  For  example,  a  no 
value  for  the  lias-pretty-forviat  s\y\tch  that  controls  pretty-printing  means  the  attribute  is 
not  to  be  included  when  its  containing  object  is  pretty-printed;  a  yes  value  means  it  is  to 
be  included;  a  nil  value  expresses  no  opinion  on  inclusion  (if  no  one  expresses  an  opinion, 
yes  is  assumed);  and  any  other  value  is  taken  to  be  a  function  that  is  called  in  place  of 
pretty-format  to  format  the  attribute  value  for  pretty-printing. 

Below  we  will  discuss  the  get  operation,  default  value,  and  pretty-format  switch  in 
more  detail.  See  the  GLOSSARY  for  details  on  the  set  and  init  operations  and  the 
uneval,  compare,  and  is-a-stub  switches.  All  the  operations  and  switches  mentioned  in 
this  section  are  reviewed  in  Table  5.2. 

15.  HAS-GET-FUNCTION'S.  The  following  attribute  descriptor  definition  supplies 
special  functions  to  get  and  set  the  has-duration  attribute  of  an-event— 

[eval-wheii  {compile  load  eval) 

[a  n-attribute- descriptor 

lias-name  ’*get-event-has-du ration-descriptor* 
has- descriptor- attribute  has-duration 
has-descriptor-type  an-event 
has-functions 

[an-attribute-function- table 
has-get-functio7i  ^event-du ration-get-function 
has-set- function  ' never-set- function 
has-init-fujiction  *  never- iriit- function))) 

{defun  event-duration-get-function  (the-descriptor  the-attribute  the-object) 
{difference  (has-stop-time  (an-event  the-object)) 

(has-start-time  (an-event  the-object)))). 

This  definition  specifies  that  if  x  is  an-event, 

(has-duration  x) 

will  be  computed  by  calling— 

{funcall  *event-duration-get-function  *get-event-has-duration-descriptor*  has-duration  x). 
This  call  will  return  the  difference  of  the  stop  and  start  times  for  x. 

The  first  argument  to  event-duration-get-function  is  the  descriptor  just  made  above, 
the  one  that  triggered  the  call  to  event-duration-get-function.  This  descriptor  is  not  used 
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TABLE  5.2 

ATTRIBUTE  OPERATIONS,  VALUES,  AND  SWITCHES 

Attribute  of 
An-Attribute-Descriptor 

Use 

Attribute  of 

An-Attribute-Function-Table 

h 

as-functions 

Get  the  value  of  the  otr.ril)ute  Irom  an  object 
of  the  given  type. 

has-get-function 
h  as- get- m  ac  r  o 

h 

as-functions 

Set  the  value  of  the  attribute  lor  an  object 
of  the  given  type. 

has-set-function 

has-set-macro 

h; 

as-functions 

Inspect  and  oplionallv  change  an  initial 
value  of  the  attribute  for  an  object  of  the 
given  type  which  is  being  made. 

has-init- function 
h  as- i  n  it- m  ac  ro 

has-default- value 

Find  the  default  value  of  the  attribute  for  an 
object  of  the  given  type  which  is  being  made. 

has- format-switch 

Determine  whether  the  attribute  is  to  appear 
in  a  pretty-printed  version  of  an  object  of 
the  given  type,  and  optionally  format  the  at¬ 
tribute  value  in  a  special  manner  when  it  is 
to  be  part  of  such  a  prettv-printing. 

has-uneval-s  witch 

Determine  whether  the  attribute  is  to  appear 
in  an  unevaluated  version  of  an  object  of  the 
given  type,  and  optionally  unevaluate  the  at¬ 
tribute  value  in  a  special  manner  when  it  is 
to  be  part  of  such  an  unevaluation. 

has-compare-switch 

Determine  whether  the  attribute’s  values  are 
to  be  compared  when  objects  of  the  given 
type  are  compared,  and  optionally  compare 
the  attribute’s  values  in  a  special  manner 
when  such  objects  are  compared. 

h  as-  is-  a-st  u  b-s  wit  ch 

Determine  whether  the  attribute  value  is  to 
be  tested  for  nil  when  an  object  of  the  given 
type  is  tested  to  see  if  it  is  a  stub,  and  op¬ 
tionally  perform  this  test  in  a  special 
manner  when  such  an  object  is  tested. 

in  the  above  example,  but  in  general  it  may  be  used  to  allov  one  function  to  get  many 
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different  attributes.  The  descriptor  has-paraineters  attribute  can  be  used  as  a  parameter 
by  this  function. 

This  has- parameters  attribute  is  an  integral  part  of  the  descriptor  so  that  il  can  be 
efficiently  accessed.  Other  attributes  special  to  an  application  may  be  defined  for  the 
descriptor,  but  they  will  not  be  accessed  as  efficiently  (as  they  will  be  placed  on  the 
descriptor’s  property  list). 

The  event-duration-get-function  is  the  has- get- June  lion  of  the  attribute  descriptor 
defined  above.  The  has- set- Junction  o{  the  same  descriptor  specifies  that— • 

(5c//(has-duration  x)  y) 

will  be  computed  by  calling— 

[Juncall^ never-set- Junction  y  *get-event-has-duration-descriptor*  has-duration  x). 

,\‘ever-sei-Junction  is  a  standard  function  supplied  by  SKETCH  which  will  print  an  error 
message  saying  that  has-duration  can  never  be  set  for  objects  of  an-evenr.  type.  *Verer- 
imt-Junction  is  similar,  and  prohibits  has-duration  from  being  initialized  when  an-event  is 
made. 

For  details  on  lias-get-Junction's^  has-set-Junction's,  and  has-init-Junction's.  see  uu- 
attribute-Junction-table  in  the  GLOSSARY. 

16.  HAS- GET-MACRO’S.  The  expression  — 

(has-duration  (an-event  xj) 

will  expand  into  a  Juncall  to  event-duration-get-function,  given  the  above  definitions  It 
would  be  nice  to  allow  event-duration-get-function  to  be  a  macro,  so  it  could  produce 
more  efficient  in-line  code.  But  this  is  not  always  possible,  because  an  expression  such 
as— 

(has-duration  x) 

does  not  know  the  type  of  x  at  compile  time,  and  therefore  must  expand  into  something 
that  does  not  locate  the  event-duration-get-function  until  eval  time.  Since  compiled  code 
cannot  call  macros  at  eval  time,  event-duration-get-function  cannot  be  a  macro. 

However,  if  we  change  the  attribute  descriptor  definition  to  add  a  has-get-macro,  ;us 

in  — 

[eval-when  {compile  toad  evat) 

{an- attribute- descriptor 

has-name  ’*get-event-has-du ration-descriptor* 
has- descriptor-attribute  has-duration 
has- descriptor- type  an-event 
has-Junctions 

{an- attribute-junction- table 
has- get- Junction  ’event-duration-get-function 
has- get-macro  ’event-duration-get- macro 
has- set- Junction  ^ never-set- Junction 
has- init- Junction  '  never-  init-Junction))), 

then— 

(has-duration  (an-event  x)) 
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will  expand  into— 

(event-duration-get- macro  ?)t.*get-event-has-du  rat  ion-descriptor*  ^.lias-duration 

(an-event  x)), 

where  the  first  two  macro  arguments  are  pre-evaluated  (see  OPERATIONS  above). 
Event-duration-get-macro  should  be  a  macro,  and  may  be  defined  by— 

(de/macro  event-duration-get-macro  (the-descriptor  the-attribute  the-object) 

'{let  ((x  , the-object)) 

[difference  (has-stop-time  (an-event  x)) 

(has-start-time  (an-event  x))))). 

Event-duration-get-function  must  still  exist,  and  will  be  called  by  the  expansion  of— 

(has-duration  x), 

which  does  not  specify  the  type  of  x  at  macro  expansion  time. 

17.  DEFAULT  VALUES.  Default  values  may  be  specified  when  types  arc  defined  by 
declare-hxink^type  or  declare-vector-ttjpe,  as  in  — 

[declare-hunk-fype  an-event 

hns-password  *event-password* 
has-name  (h;is-start-time  0) 
is-read'init‘ private 
(has-stop-time  *defaiilt-dii ration*) 
is- hidden  is-private 
has-previous-event), 

where  the  default  values  are  '0'  and  '*default-duration*’.  These  default  values  become 
the  has- default- value  attributes  of  appropriate  attribute  descriptors. 

Default  values  are  expressions  which  are  evaluated  when  needed.  They  may  refer  to 
global  variables,  such  as  ‘*default-duration*’,  but  not  to  local  variables.  .\lso,  if  one 
wants  nil  to  be  a  default  value,  one  must  use  the  non- /id  expression  'nil  (with  a  quote)  as 
a  default  value  expression. 

When  an  object  is  made,  a  search  is  made  for  default  values  declared  for  attributes 
and  associated  with  the  type  of  the  object  being  made  (see  SEARCHING  FOR  DESCRIP¬ 
TORS  below).  Default  values  are  found  as  the  has- default- value  attribute  of  an-attribute- 
descriptor's  whose  has- descriptor- type  is  the  type  of  the  object  being  made  (or  an  ancestor 
of  that  type:  see  the  has-parent  attribute  of  a-type  object  in  the  GLOSSARY),  and  whose 
has- descriptor- attribute  is  the  attribute  which  has  the  default  value  (neither  has- 
descrip tor- type  or  has- descriptor- attribute  may  be  ni[).  If  a  non-7n/  default  value  is  found, 
it  is  an  expression  which  is  evaluated  to  produce  an  initial  value  for  an  attribute  in  an 
object  being  made. 

Default  values  are  inherited.  If  a  has- default- value  attribute  is  initialized  to  nil  when 
an- attribute- descriptor  is  made,  the  attribute  will  be  reset  to  the  value  of  the  parent 
descriptor’s  has- default- value  attribute. 

18.  PRETTY-FORMAT  SWITCHES.  A  fonnat-objecf  operation  is  provided  for 
each  SKETCH  object  type  to  perform  the  duities  of  the  pretty-format  macro  for  objects  of 
that  type.  The  default  format-object  operations  provided  by  declare-hunk-type  and 
declare-vector-type  will  only  include  in  the  resulting  format  attributes  actually  stored  in 


Printed  April  27,  1989 


OBJECTS 


5-21 


the  object  which  is  to  be  pretty-printed.  Also,  only  attributes  with  non-////  values  are 
included. 

These  default  format- object  operations  search  attribute  descriptors  for  has-fonnat- 
switch^s  in  the  same  way  as  default  make-object  operations  search  for  lias-default-values. 
The  format  switch  found  for  an  attribute  is  used  to  control  inclusion  of  the  attribute 
value  in  the  object’s  format,  and  may  also  control  the  formatting  of  the  attribute  value. 

(1)  If  the  format  switch  is  no,  the  attribute  value  is  not  included  in  the  object  format. 

(2)  If  the  format  switch  is  yes,  the  attribute  value  is  included,  and  the  pretty-format 
macro  is  used  to  format  the  attribute  value  for  inclusion. 

(3)  If  the  format  switch  is  a  symbol  other  than  yes,  no,  or  nil,  that  symbol  is  used  as  a 
function  called  with  the  same  arguments  as  pretty-format  to  format  the  attribute 
value.  If  the  function  returns  a  non-nil  value,  the  attribute  is  included  in  the  object 
format,  and  the  function’s  return  value  is  taken  to  be  the  format  of  the  attribute 
value.  If  the  function  returns  nil,  the  attribute  value  is  not  included. 

(4)  A  nil  format  switch,  which  is  the  same  as  no  format  switch  being  provided  by  any 
attribute  descriptor,  is  taken  as  equivalent  to  a  yes  format  switch. 

(5)  Note  that  if  an  attribute  has  a  nil  value,  it  is  not  included  in  the  object  format,  and 
no  check  of  the  attribute’s  format  switch  is  mode. 

19.  OTHER  ATTRIBUTE  SWITCHES.  Attribute  descriptors  have  three  other 
kinds  of  sw  itches. 

The  has-uneval-switch  attribute  is  just  like  the  has- format-switch  attribute,  except  it 
is  for  the  uneval-object  operation  rather  than  for  the  format-object  optvalxow. 

The  has- compare-switch  attribute  is  similar,  but  it  is  for  the  compare-object  opera¬ 
tion.  Here  a  no  means  not  to  test  the  attribute  values  when  comparing  two  objects,  while 
a  yes  or  nil  means  to  test  the  values  with  the  equal  function.  Any  other  symbol  as  the 
switch  value  means  to  test  by  calling  the  symbol  as  a  replacement  for  the  equal  function 
The  symbol  compare-object-function  may  be  used  just  so  to  cause  attribute  values  to  be 
themselves  compared  piece  by  piece,  after  the  manner  of  compare-object.  Equal,  on  the 
other  hand,  will  consider  SKETCH  objects  to  be  different  if  they  do  not  occupy  the  same 
position  in  memory,  even  if  the  objects  have  identical  parts. 

The  has-is-a-stub  attribute  is  similar,  but  tests  attribute  values  for  nil  in  order  to 
determine  whether  an  object  is  a  stub  (see  NAMES  above). 

A  hidden  attribute,  as  described  in  the  BASIC  TYPES  section  above,  has  no  as  the 
value  of  its  has- for  mat- switch,  has-uneval-switch,  and  has-compare-switch.  A  visible  attri¬ 
bute  has  nil  as  the  value  of  these  switches.  By  chosing  different  values  for  these  switches, 
an  attribute  may  be  made  partly  visible  and  partly  hidden.  See  declar e-hunk- type  and 
declare-vec tor- type  in  the  glossary  for  how  to  specify  values  for  these  switches. 

20.  THE  FORMAT-OBJECT  OPERATION.  The  format-object  operation  does 
the  work  of  pretty-format  for  SKETCH  objects.  It  is  common  to  want  to  adjust  the 
pretty-printed  version  of  the  object  beyond  what  can  be  done  with  format  switches.  This 
is  usually  done  by  creating  a  new  copy  of  the  object  and  tinkering  with  the  attribute 
values  in  the  copy.  For  example,  to  pretty-print  an-event  objects  with  a  has-duration 
attribute  in  place  of  has-stop-time,  the  following  might  be  used— 
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(eval-when  {coiiipilc  load  eval) 

[an-operation-descriptor 
has-name  ’"^format-event-descriptor* 
has-dcscriptor-optraiion  format-object 
has-descriptOT-type  an-event 
has-function  Tormat-event)) 

(rfe/un  format-event  (the-operation-descriptor  the-operation 

the-object 
&opt{oTial  the-level 
&aux  the-event) 

[setq  the-event  {create-parent-object  ^create-event-descriptor^ 

[list  an-event)  the-object)) 

(cond  ((has-start-time  (an-event  the-event)) 

{setf  [get-parent-attribnte 

"^get-event-has-duration-descriptor*  has-duration 
(an-event  the-event)) 

(rfi[^(has-stop>-time  (an-event  the-event)) 

(has-start-time  (an-event  the-event)))) 

(5e^/(has-stop- time  (an-event  the-event)  *event-pass\vord*) 
nil})) 

(e3:ecu^c-paren^-operflh*07i  *format-event-clescTiptor*  format-object 

(an-event  the-event)  the-level)). 

This  function  creates  a  copy  of  the-object,  called  the-event.  If  the-event  is  not  a 
stub,  then  the  function  stores  an  actual  has-duration  attribute  value  in  the-event,  so  that 
that  attribute  will  print,  and  sets  the  actual  has-stop-time  attribute  of  the-event  to  nil,  so 
that  attribute  will  not  print.  Lastly,  the  function  formats  the-event  using  execute- 
parent- operation. 

In  order  to  set  the  actual  has-duration  attribute  of  the-event,  the  function  must  use 
the  parent  of  *get-event-has-duration-descriptor*,  which  was  first  introduced  in  the  HAS- 
GET- FUNCTION’S  section  above.  The  get-parent- attribute  macro  aids  in  this. 

21.  SEARCHING  FOR  DESCRIPTORS.  When  an  operation,  such  as  make-object, 
is  to  be  performed  for  a  particular  type,  a  search  for  an-operation-descriptor  is  made.  All 
the  descriptors  searched  must  have  their  has-descriptor-operation  attribute  equal  to  the 
operation  to  be  performed. 

First,  an  operation  descriptor  whose  has-descriptor-type  is  the  particular  type  of  the 
object  being  operated  on  (or  an  ancestor  of  that  type:  see  a-type  in  the  GLOSSARY)  is 
searched  for.  Such  an  operation  descriptor  is  specific  to  the  particular  type  of  object 
being  operated  on.  The  search  is  made  in  most-recently-made-first  order. 

Then,  if  no  such  specific  descriptor  is  found,  a  global  operation  descriptor  valid  for 
all  types  is  searched  for.  Such  a  global  descriptor  has  nil  as  its  has-descriptor-type. 
Again  the  search  is  made  in  most-recently-made-first  order. 

The  descriptor  that  is  found  is  passed  as  an  argument  to  the  function  or  macro 
designated  by  that  descriptor. 
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When  a  lunction,  such  as  the  has-gct- function^  is  required  for  a  particular 
type/attribute  pair,  a  search  is  first  made  among  all  attribute  descriptors  whose  /i«6- 
(lescriptor-attributc  equals  the  attribute.  As  for  operations,  the  search  begins  in  most- 
recently-made-first  order  with  descriptors  whose  has- descriptor- type  equals  the  type,or  the 
object  whose  attribute  is  being  gotten  (or  an  ancestor  of  that  type),  and  then  continues, 
again  in  most-recently-made-first  order,  to  descriptors  whose  lias-descriptor-type  is  nil. 
However,  in  this  case,  if  no  descriptor  is  found,  the  search  continues  further  to  descriptors 
whose  has-descriptor-attribute  is  nil,  but  whose  has-descriptor-type  is  the  type  of  the 
object  whose  attribute  is  being  gotten  (or  an  ancestor  of  that  type).  Again,  this  last 
search  is  made  in  most-recently-made-first  order. 

Another  difference  in  the  attribute  descriptor  case  is  that  not  all  the  descriptors 
searched  will  have  a  has- get- function.  Those  without  such  a  function  cannot  be  used,  and 
are  ignored. 

The  descriptor  that  supplies  the  has- get- function  is  passed  as  an  argument  to  that 
function. 

The  searches  for  lias-set-function's  and  has- hiit- function's  are  similar.  Searches  for 
macros  (e.g.  has-get-macro),  will  be  satisfied  by  a  descriptor  that  has  either  a  macro  or  a 
function.  If  only  the  function  is  present  (e.g.  only  has-get- fund  ion  and  not  has-get- 
nufcro),  it  will  be  used  as  if  a  macro  existed  that  simply  called  the  function. 

E.zecute-parent-operation  and  get- parent- attribute  continue  searches  from  the  point 
where  they  left  off.  If  a  first  search  for  an-operation-descriptor  found  a  descriptor  D, 
then— 

[execute-parent-operation  D  ..) 

continues  the  search  from  the  point  where  it  left  off.  Get-parent-attribute  can  be  used 
with  setf  to  continue  searches  for  setting  attributes. 

Make-parent-object  and  create-parent-object  are  used  in  place  of  execute-parent- 
object  for  the  make-object  and  create- object  opevditions,  because  these  latter  operations  do 
not  have  a  first  argument  which  is  an  object  of  the  type  to  be  used  in  searching  for  the 
descriptor.  Rather  the  first  argument  is  a  list  whose  first  element  is  that  type.  Similarly 
parent-object- is  is  used  for  the  operation,  whose  first  argument  is  the  type  itself. 

Other  non-standard  operations  can  be  created  with  help  from  the  find-operation- 
descriptor  macro  (see  the  GLOSSARY). 

Searching  for  switches  and  default  values  is  similar  to  searching  for  has-get- 
function'Sj  except  that  one  searches  instead  for  non-nil  has- default- value's,  lias-format- 
switch'es,  has-uneval-switch'es,  has-compare-switch'es,  or  has-is-a-stub-switch'es. 

22.  GENERALIZED  INDEXING.  Suppose  we  want  to  create  a  data  ba.se  contain¬ 
ing  people  defined  by— 
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(declare-hunk-type  a*person 

has-height  has-weight  has-age  ... 

'  has-t$-a-$txib~switch  'yes 

lias-name 

has-is-a-stiib-switch  *no 
has- social-security-number). 

We  want  each  person  to  be  uniquely  defined  by  his  social  security  number,  but  not  by  his 
name.  Looking  back  at  the  previous  section  on  NAMES,  we  see  that  we  want  to  define 
the  concept  of  a-person  stub  to  be  a-person  object  with  all  attributes  missing  {ntf)  except 
for  has-social-seciirit y-number.  This  is  done  by  the  two  has-is-a-stub-sxvitch  lines  in  the 
above  definition.  The  first  ensures  that  the  has-name  attribute  of  a-person  must  be  nil  in 
a  stub:  by  default  it  would  not  have  to  be  nil.  The  second  allows  the  has-social-security- 
niiinber  attribute  of  a-person  in  a  stub  to  be  non-nil. 

The  next  step  is  to  define  a  special  make-object  function  for  a-person  objects— 
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{eval-ivlien  {eval  load  compile) 

{an-operat\on-descriptor  has^descriptor-tijpe  a-person 

has- descriptor- operation  make-object  ^ 
has- function  ’make- person-function)) 

{defun  make-person-function  (the-operation-descriptor  the-operation 

the-abnormal-object  the-prototvpe 

&aux  the-new-object  the-social-security-number  the-previous-object) 

{setq  the-new-object 

(create-object  {process-attributes  the-abnormal-object  the-prototype) 
the-prototype)) 

{s€iq  the-social-security-number 

(has-social-security-number  (a-person  the-new-object))) 

{assert  {and  the-social-security-number 

{syinbolp  the-social-security-number)) 

’(has-social-security-number  attribute  is  not  a  non-nil  symbol)) 

{setq  the-previous-object 

{and  {boundp  the-social-security-number) 

{sijmeval  the-social-security-number))) 

{assert  {or  {not  the-previous-object) 

{object-is  a-person  the-previous-object)) 

‘(previous  value  of  , the-social-security-number  is  not  a-person)) 

{cond  {{not  the-previous-object) 

{set  the-social-security-number  the-new-object)) 

{{object-is- a-stub  (a-person  the-new-object)) 
the-previous-object) 

{{object-is-a-stub  (a-person  the-previous-object)) 

{move-object  the-new-object  the-previous-object) 
the-previous-object) 

{{compare-object  (a-person  the-new-object) 

(a-person  the-previous-object)) 
the-  previous-object) 

(^  {error  ’(object  made  is  not  equal  to  previous 

person  with  same  social  security  number))))) 

The  first  step  in  the  make-person-function  is  to  apply  process-attributes  to  the 
abnormal  version  of  the  object  being  made  (see  abnormal  objects  in  CREATE-OBJECT 
OPERATIONS  above).  E.g.- 

(make-person-function  <an-attribute-descriptor  D>  make-object 

{list  a-person  has-social-security-number  ’l40-90-000| 

lias-name  ’George  has-height  72  has- weight  200) 
niCj 

is  a  typical  call  to  make-person-function,  in  which  the  third  argument  is  an  abnormal 
object.  The  process-attributes  function  alters  the  abnormal  object  by  filling  in  default 
values  of  attributes  not  specified  (using  the  has- default- value  attributes  of  attribute- 
descriptors:  see  DEFAULT  VALUES  above).  It  also  applies  has-init-functionSy  if  any,  to 
non-default  attribute  values. 
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The  modified  abnormal  object  is  passed  to  create-object  to  create  (lie  a-person 
object.  The  has-social-security-number  is  e.xtractecl  from  the  resulting  object,  and 
checked  to  be  sure  it  is  a  legal  non-«/7  symbol  (in  FRANZ  lisp.  40-90*000  is  read  as  a  sym¬ 
bol,  even  if  not  surrounded  by  vertical  bars). 

The  social  security  number  is  supposed  to  be  a  unique  identifier  for  the  person,  so  in 
this  example  we  simply  set  the  symbol  value  of  the  social  security  number  to  the  person 
object.  Thus  if  there  was  a  previous  object  with  the  same  social  security  number,  it  can 
be  found  as  the  value  of  the  social  security  number. 

The  rest  of  the  function  is  as  follows— 

(1)  If  there  is  no  previous  object,  we  set  the  social  security  number  symbol 
value  to  the  new  object,  and  return  the  new  object. 

(2)  Otherwise,  if  the  new  object  is  a  stub,  we  return  the  previous  object. 

(3)  Otherwise,  if  the  previous  object  is  n  stub,  we  move  the  new  object  into 
the  previous  object  and  return  the  latter. 

(4)  Otherwise,  we  compare  the  new  and  previous  objects,  and  return  the  latter 
if  the  two  objects  are  equal. 

(5)  Otherwise,  we  signal  an  error. 


We  also  need  to  provide  special  formal-object  and  unecal-object  oper:iUons  to  output 
stubs  such  as— 

(a-person  has-social-security-number  ’ 0-90- 000 1) 

in  place  of  the  full  object  when  the  object  is  an  attribute  value  of  another  object.  The 
situation  where  the  stub  should  be  output  is  recognized  by  a  non-zero  level  argument  to 
format-object,  or  a  non-mV  index-switch  argument  to  uneval-object  (see  the  GLOSSARY). 

23.  C  TYPES.  The  OBJECTS  package  contains  some  C  language  support  code  that  is 
a  continuation  of  the  ATOMS  package.  This  continuation  makes  use  of  a-type  objects, 
which  is  why  this  code  is  not  included  in  the  ATOMS  package  to  begin  with  (the  ATOMS 
package  does  not  depend  upon  the  OBJECTS  package). 

C  code  can  obtain  a  pointer  to  any  object  with  a  lias-iiame  attribute  by  calling— 

sob^nobject  ("<name>**) 

In  particular,  the  system  has  already  done  this  for  basic  a-iijpe  objects,  such  as  a- 
chaVf  and  stored  the  results  away  in  C  global  variables,  such  as  SOB^CHAR.  The  follow¬ 
ing  table  lists  all  the  global  C  variables  set  to  a-type  objects  in  this  manner— 
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C  Global 
Variable 

SKETCH 
a-type  Object 

C  Global 
Variable 

SKETCH 
a-type  Object 

SOB_ATTRIBUTE 

a7i-attribute 

SOBJLONG 

a-long 

SOB_BIGNUM 

a-bignum 

SOBJL  VECTOR 

a-lisp-vector 

SOBJBINARY 

a-binary- function 

SOB_NONLISP 

a-non-lisp-ifalue 

SOB.CHAR 

a-char 

SOB_PORT 

a-port 

SOBJDOUBLE 

a- double 

SOB.SHORT 

a-short 

SOB_FIXNUM 

a-fixnum 

SOB.STRING 

a-string 

SOB_FLOAT 

a-float 

SOB.SYMBOL 

a-syrnbol 

SOB_FLONUM 

a^Jionum 

SOB_TYPE 

a-type 

SOB_HUNK 

a-hunk 

SOB.UBIT 

a-ubit 

SOBJNT 

an-int 

SOB.UCHAR 

a-ncliar 

SOB_rVECTOR 

an-immediate- vector 

SOB.ULONG 

a-nlong 

SOB_LARRAY 

a-lisp-array 

SOB.UNSIGNED 

(tii-u  nsiyned 

SOBJLBIT 

an-lbit 

SOB.USHORT 

ii-ushort 

SOB_LIST 

a- list 

SOB.VALUE 

a-ralue 

The  C  data  type  sob^type  is  defined  to  be  a  pointer  to  n-tijpe  object.  The  C  data 
type  bob^attrtbule  is  defined  to  be  a  pointer  to  an- attribute  object. 

There  is  a  C  equivalent  of  the  has-lisp-type  function;  sob^ltijpe.  'Phis  is  actually  a 
fast  macro.  An  example  of  its  use  is— 

ifisobjtype  (x)  -=  SOBJ^IXNUM)  ...  . 

There  is  also  a  C  function,  sob^tsize,  to  get  the  bas-size  attribute  of  a-type  object  (the 
number  of  bits  taken  by  a  datum  of  the  given  type  when  it  is  an  array  element) 

To  allow  code  that  deals  with  different  types  of  numbers  to  use  the  C  case  statement 
(which  can  only  test  integers  known  at  compile  time,  and  cannot  test  pointers),  there  is  a 
function,  sob^tcase,  that  returns  an  integer  code  for  numeric  types.  E.g.. 

sob^tcase  {SOB^CHAR) 

returns  an  integer  equal  to  the  C  manifest  constant  SOB^CCASE.  The  following  is  a 
table  of  the  codes  returned— 
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Ty type  Value 

Code  Returned 

Numeric  Type 

SOB UBIT 

SOB.UBCASE 

unsigned  1  bit  integer 

SOB CHAR 

SOB.CCASE 

signed  8  bit  integer 

SOB UCHAR 

SOB.UCCASE 

unsigned  8  bit  integer 

SOB SHORT 

SOB.SCASE 

signed  16  bit  integer 

SOB USHORT 

SOB.USCASE 

unsigned  16  bit  integer 

SOB_LONG 

SOBJNT 

SOBj:.CASE 

signed  32  bit  integer 

SOB_ULONG 

SOB.UNSIGNED 

SOB.ULCASE 

unsigned  32  bit  integer 

SOB FLOAT 

SOB FCASE 

signed  32  bit  floating  point  number 

SOB_DOUBLE 

SOB_DCASE 

unsigned  64  bit  floating  point  number 

There  is  another  function,  sob^tviissing,  what  will  return  the  missing  value  for  particular 

numeric  type,  given  the  sob_case  code  of  that  type.  The  missing  value  returned  is  always 

a  double.  For  example, 

sob^tniissing  (SOB^CCASE) 

returns  SOB^CMISSING  cast  to  a  double.  For  unsigned  integers,  soh^tmifi.swg  returns 

some  value  that  can  never  be  taken  by  the  integer. 

24.  HITLIST. 

(1)  Possibly  add  inheritance  under  the  constraint  that  the  underlying  format  of  related 
objects  is  the  same. 

(2)  Possibly  make  compare-object  really  test  equality  of  fixnums  with  flonums. 

(3)  Find  out  why  (get-attribute  xxx  yyy)  (type  of  yyy  not  available  at  compile  time)  is 
so  slow  and  try  to  fix  it.  Also  make  compiled  version  more  compact.  Maybe  use  C 
code? 

(4)  Possibly  make  has-vector-C- element- type  attribute  be  non-hidden. 

(5)  Consider  not  allocating  separate  hunk  part  of  vector  object  with  2  element  hunk 
part  until  property  list  is  set  (use  constant  hunk  part  in  the  meantime). 

(6)  Possibly  return  component  length  as  part  of  pretty-print  format,  so  better  judge¬ 
ments  can  be  made  using  prinlength. 

(7)  Possibly  implement  different  levels  of  verbosity  in  printing. 

(8)  Possibly  make  sob_unbound  handle  abbreviations. 

(9)  Possibly  disable  special  consideration  of  has-name  by  default  declare- hunk- type  and 
declare- vector- type  provided  format-object  and  uneval-object  functions  if  its  lias-ts- 
a-stub-switch  is  not  no. 

(10)  Possibly  outlaw  allowing  the  parentheses  to  be  omitted  from  (s_attribute),  on  the 
grounds  that  misspelled  options  (e.g.  is-read  instead  of  is-read-private)  are  mistaken 
for  attributes. 
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25.  GLOSSAJRY. 

a-bignum 

^SKETCH  Typei 

a-binary-function 

[SKETCH  Type) 

a-char 

[SKETCH  Type] 

a-double 

[SKETCH  Type] 

a-fixnum 

■  [SKETCH  Type) 

a-float 

[SKETCH  Type] 

a-floDum 

[SKETCH  Type) 

a-hunk 

[SKETCH  Type) 

an-  im  med  iate- vector 

[SKETCH  Type] 

an-int 

[SKETCH  Type] 

an-lbit 

[SKETCH  Type] 

a- lb  p- array 

[SKETCH  Type! 

a-lbp-vector 

[SKETCH  Type] 

a-lbt 

[SKETCH  Type) 

a-Iong 

[SKETCH  Type' 

a-non-Ibp- value 

[SKETCH  Type) 

a- port 

[SKETCH  Type] 

a-short 

[SKETCH  Type 

a-string 

[SKETCH  Type! 

a-symbol 

[SKETCH  Type. 

a-ubit 

[SKETCH  Type' 

a-uchar 

[SKETCH  Type^ 

a-ulong 

[SKETCH  Type 

an-unsigned 

[SKETCH  Typej 

a-ushort 

[SKETCH  Type) 

a- value 

(SKETCH  Type] 

USE:  These  are  types  of  C  and  LISP 

values  according  to  the  following  table— 

Printed  April  27,  1989 


OBJECTS 


5-30 


a-bignum 

LISP  bignxim:  large  integer. 

a- binary-function 

LISP  binary',  compiled  function. 

a-char 

C  char:  8  bit  signed  integer. 

a-double 

C  double:  64  bit  floating  point  number. 

a-fixnum 

LISP  fixnuin:  small  integer. 

a-float 

C  float:  32  bit  floating  point  number. 

a-flonum 

LISP  flonum. 

a-hunk 

LISP  hunkO,  hunkJ,  ...,  or  hiinkb. 

an-immediate-vector 

LISP  vectori. 

an-int 

C  int:  32  bit  signed  integer. 

an-lbit 

C  1  bit  unsigned  integer  for  which  the  value 

0  denotes  nit  and  the  value  1  denotes  t. 

a-lisp-array 

LISP  array. 

a-lisp-vector 

LISP  vector 

a- list 

LISP  list. 

a- long 

C  tony:  32  bit  signed  integer. 

a-non-lisp-value 

LISP  other. 

a- port 

LISP  I/O  port. 

a-short 

C  short:  16  bit  signed  integer. 

a-string 

LISP  string. 

a-symbol 

LISP  symbol. 

a-ubit 

C  1  bit  unsigned  integer. 

a-uchar 

C  uchar:  8  bit  unsigned  integer. 

a-ulong 

C  utong:  32  bit  unsigned  integer. 

an-unsigned 

C  unsigned:  32  bit  unsigned  integer. 

a-ushort 

C  ushort:  16  bit  unsigned  integer. 

a-value 

LISP  value. 

“abnormal  object”  [SKETCH  Term] 

USE:  An  ‘abnormal  object’  is  a  list  which  represents  an  object.  The  first  list  element  is 
the  type  of  the  object,  and  the  rest  of  the  elements  are  attribute  label/value  pairs. 
The  object  type  is  itself  a- type  object ^  and  not  the  symbol  naming  the  type.  Simi¬ 
larly  the  attribute  labels  are  an-attribute  objects,  and  not  symbols. 

An  example  of  an  abnormal  object  is— 

{list  a-person  has-weight  99  has-age  13) 
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(abnormal-object-for-macro  '{list  s_type  s_attribute  g_value  ...))  [LISP  Function) 
RETURNS:  The  list- 

(s_type  s_attribute  g_value  ...) 

if  the  argument  is  formatted  as  indicated  and  the  type  and  all  the  attributes 
are  represented  by  their  names.  In  this  case  get  may  be  applied  to  get 
g^value’s  from  the  returned  list. 

Otherwise  returns  niV  (and  does  NOT  call  error). 

(an-attribute  has-name  *s_name)  [SKETCH  Type  Macro) 

an-attribute  [SKETCH  Type) 

at_  [SKETCH  Argument  Prefix) 

USE:  An-attribute  serves  as  a  label  for  an  attribute  value  of  a  SKETCH  object.  See 
s^attribute. 


Whenever  an  attribute  is  gotten,  set,  initialized,  pretty-printed,  unevaliiated,  or 
compared,  the  attribute  and  the  type  of  the  object  being  referenced  are  used 
together  to  find  an- attribute- descriptor  that  specifies  functions,  macros,  and  param¬ 
eters  to  do  these  tasks.  See  an-attribnte-descriplor. 

.-VRGUMENT  PREFIX:  Attribute  arguments  are  indicated  by  the  prefix  at^. 

H. A.S-NAME:  Each  attribute  MUST  have  a  name  which  is  a  symbol.  By  convention,  this 

name  should  begin  with  an  auxiliary  verb  or  a  preposition  followed  by  a 
hyphen:  e.g.  has-parent  and  has- parameters.  See  has- name. 

I. NDEXING:  Whenever  an  attribute  is  indexed,  the  name  of  the  attribute  has  its  function 

definition  set  if  it  was  previously  nil.  This  is  also  done  for  stubs,  as  a  stub 
may  be  a  completely  defined  attribute. 


{an-attribute-descriptor  [has- de'scriptor- type  ’ty_type)  [SKETCH  Type  Macro) 

[has-descriptor-attribute  *at_attribute) 

[has-Junctions  *aft_attribute-function- table) 

[has-parameters  'g_parameters) 

[has-injo  *g_info) 

[has-default-value  *g_default- value] 


[has-is- a- stub- switch 
[has- comp  are- switch 
[has-Jormat-switch ’s, 
[has-uneval- switch ’s. 

an-attribute-descriptor 
atd_ 

(has-parent  ’atd.descriptor) 
(has-descriptor-type  *atd_descriptor) 
(has-descriptor-attribute  ’atd^descriptor) 
(has-functions  ’atd^descriptor) 
(has-parameters  *atd_descriptor) 

(has-info  ’atd_descriptor) 

(has-default-value  ’atd_descriptor) 


’s_is-a-stub-switch) 

’s_com  p  are-s  w  itch] 

.format-switch) 

.uneval-switch]) 

(SKETCH  Type) 
[SKETCH  Argument  Prefix) 
[SKETCH  Attribute  Macro) 
[SKETCH  Attribute  Macro] 
[SKETCH  Attribute  Macro) 
[SKETCH  Attribute  Macro] 
[SKETCH  Attribute  Macro) 
[SKETCH  Attribute  Macro) 
[SKETCH  Attribute  Macro) 
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(has-is-a-stub-switch  'atd.clescriptor) 
(has-compare-switch  ’atd.clescriptor) 
(has- format-switch  ’atcLdescriptor) 
(has-uneval-switch  ’atd_descriptor) 


[SKETCH  Attribute  Macroi 
[SKETCH  Attribute  Macro] 
[SKETCH  Attribute  Macro) 
[SKETCH  Attribute  Macro) 


USE  ONLY  WHEN:  Defiiiing  non-standard  SKETCH  types  and  attributes. 


USE:  An-attribute-descriptor  describes  how  a  particular  attribute,  at_attribute,  is  stored 
in  objects  of  a  particular  type,  ty^type.  At^attribute  may  be  nil  to  indicate  that 
the  descriptor  applies  to  all  attributes  of  objects  of  type  ty_type.  Ty_type  may  be 
nil  to  indicate  that  the  descriptor  applies  to  at_attribute  for  all  objects,  regardless 
of  type.  At^attribute  and  ty^type  may  not  both  be  nil. 


See  SEARCH  ORDER  below  to  find  which  attribute  descriptor  is  used  when 
several  have  the  same  at_attribute  and  ty_type. 

ARGUMENT  PREFIX:  .\ttribute  descriptor  arguments  are  indicated  by  the  prefix 
HAS-DESCRIPTOR-.ATTRIBUTE:  At_attribute:  an-attribuie  or  nil. 

H.\S-DESCRIPTOR-T\PE:  Ty.type:  a-lypeoi  nil. 

HAS-FUNCTIONS:  An- nttribxite- function- table  or  nil.  The  functions  and  macros  in  this 
table  are  used  to  get  values  from,  set  values  into,  and  check  initial 
values  of  the  attribute. 


When  two  attribute  descriptors  are  compared  by  compare-object,  their 
lias-functions  attributes  are  compared  by  compare-object  instead  of  by 
equal.  This  permits  an-attribute-descriptor  with  a  lias-name  to  be 
repeatedly  defined  as  long  as  all  the  definitions  are  the  same,  even  if 
the  lias-functions  attribute  value  does  not  itself  have  a  name  (see  stub). 

HAS- PARAMETERS:  Any  LISP  value.  Used  by  the  lias-functions  functions  and  macros. 

Can  be  setf. 

HAS-INFO:  Just  like  has-parameters  but  is  not  visible:  is  not  printed  or  represented  in  the 
unevaluated  attribute  descriptor.  Useful  for  cross  reference  lists. 

HAS-DEFAULT-VALliE:  An  evaluatable  LISP  expression.  Evaluated  when  an  object  is 

made  to  provide  a  default  value  for  the  attribute.  Cannot  refer  to 
local  variables. 


If  initialized  to  nij  will  be  set  to  the  default  value  of  the  parent  of 
this  descriptor  (see  below),  if  any. 

HAS-IS-A-STUB-SWlTCH:  A  symbol.  If  no,  this  attribute  is  not  tested  to  see  if  it  has  any 

particular  value  (such  as  nil)  in  order  to  verify  that  an  object  is 
a  stub.  If  yeSj  the  attribute  is  tested  by  the  not  function,  and 
must  be  nil  if  the  object  is  a  stub.  If  ni7,  no  opinion  on  testing 
the  attribute  is  expressed  (if  everyone  expresses  no  opinion,  the 
result  is  the  equivalent  of  yes).  If  some  other  symbol,  then  this 
is  the  name  of  a  function  which  is  called  in  place  of  not  to  test 
the  value  of  the  attribute  to  see  if  it  is  acceptable  for  a  stub. 

If  initialized  to  ni7,  will  be  set  to  the  is-a-stub  switch  of  the 
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parent  of  this  descriptor  (see  below),  if  any. 

HAS-COMP.\RE-SVVITCH:  A  symbol.  If  no,  this  attribute  is  not  tested  when  two  objects 

are  compared  for  equality.  If  yes,  the  attribute  values  for  the 
two  objects  are  tested  by  the  equal  function  if  they  are  numbers, 
strings,  or  lists,  and  by  the  eq  function  otherwise.  If  nil,  no 
opinion  on  testing  the  attribute  is  expressed  (if  everyone 
expresses  no  opinion,  the  result  is  the  equivalent  of  j/«).  If  some 
other  symbol,  then  this  is  the  name  of  a  function  which  is  called 
in  place  of  equal  or  eq  to  test  the  two  value  of  the  attribute  to 
see  if  they  are  equal. 

If  initialized  to  nil,  will  be  set  to  the  compare  switch  of  the 
parent  of  this  descriptor  (see  below),  if  any. 

H.AS-FORMAT-SVVITCH:  A  symbol.  If  no,  pretty-printing  this  attribute  is  suppressed  If 

yes,  pretty-printing  is  required,  and  pretty-format  is  called  to  for¬ 
mat  the  value  of  the  attribute  for  printing.  If  nil,  no  opinion  on 
printing  is  expressed  (if  everyone  expresses  no  opinion,  the  result 
is  the  equivalent  of  yes).  If  some  other  symbol,  then  this  is  the 
name  of  a  function  which  is  called  in  place  of  pretty-format  to  for¬ 
mat  the  value  of  the  attribute.  However,  should  this  function 
return  nil,  the  attribute  will  not  be  printed. 

If  initialized  to  nil,  will  be  set  to  the  formal  switch  of  the  parent 
of  this  descriptor  (see  below),  if  any. 

I  LAS- UNEVAL- SWITCH:  A  symbol.  If  no,  inclusion  of  this  attribute  in  the  results  of 

xineval- object  is  suppressed.  If  yes,  inclusion  is  required.  If  nil,  no 
opinion  on  inclusion  is  expressed  (if  everyone  expresses  no  opinion, 
the  result  is  the  equivalent  of  yes).  If  some  other  symbol,  then 
this  is  the  name  of  a  function  which  is  called  in  place  of  uneval- 
object  to  unevaluated  the  value  of  the  attribute.  However,  should 
this  function  return  nil,  the  attribute  will  not  be  included  in  the 
results.  The  function  may  return  'nil  to  force  inclusion  of  the 
attribute  with  the  value  nil. 

If  initialized  to  nil,  will  be  set  to  the  uneval  switch  of  the  parent 
of  this  descriptor  (see  below),  if  any. 

HAS-PARENT:  An- attribute- descriptor  ox  nil.  Automatically  set  (may  not  be  initialized  or 
self)  to  the  last  attribute  descriptor  indexed  before  this  one  which  has  the 
same  at_attribute  and  either  the  same  ty_type,  or  a  type  that  is  an  ances¬ 
tor  of  ty_type.  The  parent  of  an  attribute  descriptor,  the  parent's  parent, 
the  parent's  parent's  parent,  etc.  are  said  to  be  ancestors  of  the  attribute 
descriptor. 

SELARCH  ORDER:  When  an  attribute,  at_attribute,  is  gotten  from  or  set  into  an  object  of 
type  ty_type,  or  set  to  an  initial  value  when  the  object  is  made,  an- 
attribute- descriptor  must  be  found,  and  the  appropriate  has-functions 
function  selected  to  perform  the  get,  set,  or  init.  A  search  is  made  of 
three  groups  of  descriptors.  Each  group  consists  of  all  descriptors  with 


Printed  April  27,  1989 


OBJECTS 


5-34 


particular  values  of  their  has-det^criptor-attribute  and  lias-descriptor- 
type  attributes  as  follows— 


group 

has- descript  or- attribute 

has- descriptor- type 

1 

at_attribute 

ty_type  or  an 
ancestor  of  ty type 

2 

at attribute 

nil 

3 

nil 

ty_type  or  an 
ancestor  of  ty_type 

The  search  examines  each  of  the  three  groups  in  order.  Each  group  is 
examined  by  examining  all  descriptors  in  the  group  in  most-recently- 
made-first  order.  This  can  be  clone  by  examining  first  the  most  recently 
made  descriptor  in  each  group,  called  the  head  of  the  group,  and  then 
examining  the  head  descriptor’s  parent,  that  parent’s  parent,  and  so 
forth,  until  all  ancestors  of  the  group  head  have  been  examined. 

The  search  stops  when  a  descriptor  is  found  whose  has-get-function, 
has-sel-funclion,  or  has-init- fit  action  is  non-7u7. 

When  an  object  of  type  ty_type  is  made,  a  similar  search  is  made  for 
non-7n7  has-default-valne's.  When  an  object  is  tested  by  objeci-is-a-stub 
or  compare- object^  a  similar  search  is  made  for  non-ni7  lias-is-a-stub- 
switches  or  has- compare- sxvitch^s.  When  an  object  is  pretty- printed  or 
uneval-objecCed,  a  similar  search  is  made  for  non-7n7  has-format- 
switch^s  or  has-uneval- switch's. 

Sometimes  a  search  does  not  begin  at  the  beginning,  but  instead  begins 
just  after  a  particular  descriptor  in  the  order,  thus  in  effect  continuing 
the  previous  search  which  found  that  descriptor. 

ORDER  OF  MAKING:  The  assumption  is  made  that  all  attribute  descriptors  with  the  same 
has-descriptor-type  and  has- descriptor- attribute  are  made  in  the 
same  order  in  both  the  compile  and  evaluation  environments.  The 
get- attribute- descriptor  function  and  all  the  macros  that  use  it 
depend  upon  this  assumption. 

It  is  an  error  to  make  a  descriptor  with  a  non- Tit/  ty_type  if  ty_type 
is  the  ancestor  of  any  other  type.  Thus  all  the  descriptors  for  a  type 
must  be  made  before  the  type  is  made  a  parent  of  another  type. 

NIL  DEFAULT  VALUES:  To  set  a  has- default- value  attribute  to  an  expression  which  evalu¬ 
ates  to  Tit/,  one  must  use 

{an-attribute-descriptor  ...  has- default- value  "nil ...) 

This  is  necessary  only  if  a  non- Tit/  default  value  from  some  ances¬ 
tor  of  the  descriptor  must  be  overridden.  If  there  are  no  non-nil 
default  values,  the  default  value  will  be  nil. 
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INDEXING:  An-attribute-descriptor  may  be  indexed  by  a  lias-iiarne  attribute  in  the  nor¬ 
mal  way.  It  is  also  referenced  by  a  variety  of  indices  which  enal)Ie  the  search 
described  above.  Just  before  indexing, 

(execulc-found-operatio7i 

{find- operation- descriptor  nil  index- attribute- descriptor  tv^type) 
index- attribute- descriptor  atd^descriptor  ty_type) 

is  executed  if  the  call  to  find- operation  returns  uon-nii  The  value  returned 
by  this  operation  replaces  atd^descriptor  as  the  value  to  be  returned  by  the 
descriptor  making  operation.  This  value  is  the  descriptor  that  is  indexed, 
provided  it  is  not  a  stub  and  has  never  been  indexed  before.  The  returned 
value  may  be  a  stub,  or  any  attribute  descriptor,  either  previously  indexed, 
or  never  before  indexed. 


(an-attribute-funct  ion-table 
[has- get- function  ’s_get-function 
[has-get-macro  ’s_get- macro)] 
[has-set- function  ^s_set-function 
[/las-se^-macro  ^s_set- macro]] 
[has- init- function  ^s_i nit-function 
[/ios-jni7- macro  ’s_init- macro]]) 
an-attribute-  function-table 
aft_ 

(has-get-function  ^aft_table) 
(has-get-macro  ^aft_table) 
(has-set-function  ^aft_table) 
(has- set- macro  'aft_table) 
(has-init-function  ^aft_table) 
(has-init-macro  ’aft_table) 


[SKETCH  Type  Macro] 


SKETCH  Tvpe] 
[Argument  Prefix] 
[SKETCH  Attribute  Macro] 
[SKETCH  Attribute  Macro] 
[SKETCH  .Attribute  Macro] 
[SKETCH  Attribute  Macro] 
[SKETCH  Attribute  Macro] 
[SKETCH  Attribute  Macro] 


USE  ONLY  WHEN:  Defining  non-standard  SKETCH  types  and  attributes. 

ARGUMENT  PREFIX:  An- attribute- function- table  arguments  are  indicated  by  the  prefix 
aft_. 


USE:  An- attribute- function- table  provides  a  set  of  functions  and  macros  to  access  an 
attribute,  at_attribute,  of  an  object,  ob_object,  of  a  particular  type,  ty_type. 
Functions  and  macros  are  provided  to  get  or  set  the  attribute  value,  and  to  inspect 
and  change  initial  values  of  the  attribute. 


Let  s_attribute  be  the  name  of  at_attribute,  and  s_type  be  the  name  of  ty_type. 
Let  atd_descriptor  be  the  attribute  descriptor  which  is  to  be  used  to  access  the 
attribute,  and  whose  has-functions  equals  the  attribute  function  table  that  is  to 
supply  the  functions  and  macros.  Then  the  function  table  has  the  following  com¬ 
ponents,  all  of  which  are  functions  callable  by  funcall  or  macros  callable  by  expan¬ 
sions  of  other  macros. 


HAS-GET-FUNCTION:  Calls  of  the  form- 


and  — 


(s_attribute  ob_object  ...) 


Printed  April  27,  1989 


OBJECTS 


5-36 


{get-attribute  at_attribute  ob^object  ...) 
may  be  computed  by  the  call— 

(/unco// s_get-function  atd_descriptor  at.attribute  ob_object  ...) 

HAS-GET-MACRO:  Calls  of  the  form- 

(s^attribute  (s_type  ob^object ...)  ...) 

and— 

{get- attribute  s_attribute  (s_type  ob_object  ...)  ...) 
may  be  expanded  by  macros  into— 

(s_get-macro  atd_descriptor  at_attribute  (s_type  ob_object  ...)  ...) 
where  at_attribute  and  atd_descriptor  are  pre-evaluatecl. 
HAS-SET-FUNCTION:  Calls  of  the  form- 

(5c//(s_attribute  ob_object  ...)  g^value) 

and— 

{setf  {get-attribute  at_attribute  ob_object  ...)  g_value) 
may  be  computed  by  the  call— 

(/unco// s^et-function  g^value  atcLdescriptor  at_at tribute 
ob_object  ...) 

HAS-SET-MACRO:  Calls  of  the  form- 

(5c//(s_attribute  (s_type  ob^object  ...)  ...)  g_value) 

and— 

{setf  {get-attribute  s_attribute  (s_type  ob_object  ...)  ...) 
g_value) 

may  be  expanded  by  macros  into— 

(s_set-macro  g_value  atd_descriptor  at_attribute 
(s_type  ob_object  ...)  ...) 

where  at^attribute  and  atd_descriptor  are  pre-evaluated. 

HAS-INIT-FUNCTION:  Calls  to  make  an  object  of  type  ty^type  invoke  either  a  has-init- 
function  or  a  has-init-macro  on  all  explicitly  given  initial  attribute 
values  for  which  these  functions  or  macros  are  available.  However, 
such  calls  are  never  made  for  default  attribute  values. 

The  call  to  a  has-init-function  has  the  form— 

(/unco// s_init-fu action  g_value  atd_descriptor  at_attribute 
ty_type) 

The  value  returned  by  this  call  is  used  as  the  value  to  assign  to  the 
attribute. 

HAS-INIT-MACRO:  The  call  to  a  has-init-macro  (see  HAS-INlT-FUNCTlON  above)  has 
the  form  — 
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(s_init-macro  g^value  atd_descriptor  at.attribute  ty_type) 

where  ty.type,  at_attribute,  and  atd_descriptor  are  pre-evaluated. 
The  value  returned  by  this  expression  when  it  is  evaluated  is  used  as 
the  value  to  assign  to  the  attribute. 

CONSTRAINT:  If  a  macro  attribute  of  an-attribute- function-table  is  non-ni7,  the  associ¬ 
ated  function  attribute  must  also  be  non-nil.  The  reverse  is  not  true:  if  a 
macro  is  needed,  and  only  a  function  is  found,  the  function  will  be  used  in 
place  of  the  macro. 

(an-operation  has-name  *s_name  [SKETCH  Type  Macro] 

has- index- subscript  ’x_index-subscript) 

an-operation  [SKETCH  Type] 

op_  [SKETCH  Argument  Prefix] 

*operation-lndex-size*  [LISP  Global  Variable] 

(has-index-subscript  ’op_operation)  [SKETCH  Attribute  Macro] 

USE:  An-operation  serves  as  a  name  for  an  operation  that  may  be  performed  on  different 
types  of  SKETCH  object  in  a  manner  depending  upon  the  type  of  the  object 
operated  on.  See  s^operation. 

Whenever  an  operation  is  performed  upon  an  object  of  a  given  type,  the  operation 
and  type  together  are  used  to  select  an- operation- descriptor  that  supplies  a  func¬ 
tion  and  additional  parameters  to  that  function  to  perform  the  operation.  A 
macro  may  also  be  supplied  to  expand  the  operation  more  efficiently  at  compile 
time. 

ARGUMENT  PREFIX:  Operation  arguments  are  indicated  by  the  prefix  op_. 

HAS-NAME:  Each  operation  MUST  have  a  name  which  is  a  symbol.  By  convention,  this 
name  usually  contains  an  active  verb:  e.g.,  make-object  and  format-object. 
See  has-name. 

HAS-INDEX-SUBSCRIPT:  Each  type  has  an  operation  index  table  associated  with  it  which 

is  used  to  more  rapidly  look  up  operation  descriptors  associated 
with  the  type.  Operation  objects  can  be  assigned  an  integer, 
their  has-index-subscript^  which  is  their  subscript  in  these  tables. 
Assigning  such  a  subscript  speeds  up  execution  of  the  operation. 

No  two  operations  may  have  the  same  subscript,  unless  the  two 
operations  are  never  defined  for  the  same  type.  On  the  other 
hand,  if  every  operation  were  assigned  a  different  subscript,  the 
index  tables  would  be  exceptionally  large. 

If  the  has-index-subscript  attribute  is  not  initialized,  its  value 
becomes  m7,  and  the  operation  is  not  speeded  up.  If  the  attri¬ 
bute  is  initialized  to  an  integer,  that  integer  is  used  as  a  sub¬ 
script.  If  the  attribute  is  initialized  to  a  non-«i7,  non-integer 
value,  the  value  of  the  global  variable  *operation-index-size*  is 
becomes  the  actual  value  of  the  has-index-subscript  attribute, 
and  that  variable  is  incremented  by  1.  The  value  of  this  variable 
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is  the  size  of  any  newly  allocated  index  table.  In  any  case,  the 
value  of  this  variable  is  maintained  at  one  larger  than  the  max¬ 
imum  of  all  operation  has-\ndcx-$iibscript  attributes. 


Previously  allocated  tables  are  not  increased  in  size,  and  there¬ 
fore  subscript  assignment  may  not  speed  new  operations  added 
to  old  types.  Index  tables  are  not  defined  for  a  type  until  the 
first  definition  of  an  operation  descriptor  for  the  type  is  made. 
Thus  it  is  desirable  to  define  all  operations  used  with  a  type 
before  defining  any  operation  descriptors  for  the  type. 

INDEXING:  Whenever  an-opcration  is  indexed,  the  name  of  the  operation  has  its  function 
definition  set  if  it  was  previously  nil.  This  is  also  done  for  stubs,  as  a  stub 
may  be  a  completely  defined  operation.  See  s^opcratioji. 

Replacement  of  non-ni7,  non-integer  lias-index’swbscript  attributes  and  updat¬ 
ing  *op€rat{on-indcX‘s{zc*  \s  also  done  at  operation  indexing  time. 


(an-operation-descriptor  [has-descriptor-type  ’ty_type]  [SKETCH  Type  MacroJ 

Itas-descriptor- operation  'op_operation 
has-fnnetion  ’s_operation- function 
[has-macro  ’s_operation-macroj 
[has-parameters  ’g^parameters] 

\has-info  *g_info]) 


an-operation-descriptor 

opd_ 

(has-parent  ’opd_descriptor) 
(has-descriptor-type  ’opd_descriptor) 
(has-descriptor-operation  ’opd_descriptor) 
(has-function  ’opd_descriptor) 

(has-macro  ’opd_descriptor) 
(has-parameters  *opd_descriptor) 

(has-info  *opd_descriptor) 


[SKETCH  Type; 
[SKETCH  .\rgument  Prefix) 
[SKETCH  Attribute  Macroj 
[SKETCH  Attribute  Macroj 
[SKETCH  Attribute  Macro) 
[SKETCH  Attribute  Macro] 
[SKETCH  Attribute  Macro] 
[SKETCH  Attribute  Macro] 
[SKETCH  Attribute  Macro] 


USE  ONLY  WHEN:  Defining  non-standard  SKETCH  types  and  operations. 


USE:  An-operation-descriptor  describes  how  a  particular  operation,  op^operation,  is  exe¬ 
cuted  for  objects  of  a  particular  type,  ty_type.  Ty_type  may  be  nit  to  indicate 
that  the  descriptor  applies  to  op_operation  for  all  objects,  regardless  of  type. 
Op_operation  may  not  be  ni7. 


ARGUMENT  PREFIX:  Operation  descriptor  arguments  are  indicated  by  the  prefix  opd^. 
HAS-DESCRIPTOR-OPERATION:  Op_operation:  an- operation. 

HAS-DESCRIPTOR-TYPE:  Ty_type:  a-type  or  ni7. 

HAS-FUNCTION:  A  non-m7  symbol.  Calls  such  as  those  of  the  form  — 


{s_operation  ob_object  ...), 


{exeente-operation  op_oper^t\on  ob.object  ...) 
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and 

{exccute-found- operation  opd^descriptor  op_operation  ob_object  ...) 
may  be  computed  by  the  call— 

(/unco// s_operation-function  opdjescriptor  op_operation  ob_object  ...) 

HAS-MACRO:  Calls  such  as  those  of  the  form— 

(s.operation  (s_type  ob_object  ...)  ...) 


(cxecufc-opcrofion  op.operation  (s_type  ob_object  ...)  ..  ) 


or 


[execute-found-operation  opd_descriptor  op_operation 

(s_type  ob_object  ...)  ...) 

may  be  expanded  by  macros  into— 

(s_operation-macro  opd_descriptor  op_operation  (s_type  ob_object  ...)  ...) 

In  this  last  call  op_operation  and  opd_descriptor  are  pre-evaluated. 

H.\S-P.ARAMETERS:  Any  LISP  value.  Used  by  the  has-finiction  function  and  has-macro 
macro.  Can  be  self. 

FLAS-INTO:  Just  like  has-parameters  but  is  not  visible:  is  not  printed  or  represented  in  the 
unevaluated  operation  descriptor.  Useful  for  cross  reference  lists. 

H.\S-PAHENT:  Aii-operation-descriptor  or  nil.  Automatically  set  (may  not  be  initialized 
or  self)  to  the  last  operation  descriptor  indexed  before  this  one  which  has 
the  same  op_operation  and  either  the  same  ty_type,  or  a  type  that  is  an 
ancestor  of  ty_type.  The  parent  of  an  operation  descriptor,  the  parent’s 
parent,  the  parent's  parent’s  parent,  etc.  are  said  lo  be  ancestors  of  the 
operation  descriptor. 

SEARCH  ORDER:  When  an  operation,  op_operation,  is  to  be  executed  for  an  object  of 
type  ty.type,  an-operation- descriptor  must  be  found.  A  search  is  made 
of  two  groups  of  descriptors.  Each  group  consists  of  all  descriptors 
with  particular  values  of  their  has-descriptor-operation  and  has- 
descriptor-type  operations  as  follows— 


group 

has-descriptor-operation 

has-descriptor-type 

1 

op_operation 

ty_type  or  an 
ancestor  of  ty type 

2 

op_operation 

nil 

The  search  examines  each  of  the  two  groups  in  order.  Each  group  is 
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examined  by  examining  all  descriptors  in  the  group  in  most-recently- 
made-first  order.  This  can  be  done  by  examining  first  the  most  recently 
made  descriptor  in  each  group,  called  the  head  of  the  group,  and  then 
examining  the  head  descriptor's  parent,  that  parentis  parent,  and  so 
forth,  until  all  ancestors  of  the  group  head  have  been  examined. 

The  search  stops  when  a  descriptor  is  found  (all  operation  descriptors 
must  have  non-m7  has-function  attributes,  so  any  operation  descriptor 
examined  will  do). 

Sometimes  the  search  does  not  begin  at  the  beginning,  but  instead 
begins  just  after  a  particular  descriptor  in  the  order,  in  effect  resuming 
the  previous  search  which  found  that  descriptor. 

ORDER  OF  MAKING:  The  assumption  is  made  that  all  operation  descriptors  with  the 
same  has-dcscriptor-typc  and  has-dcscriptor-opcration  are  made  in 
the  same  order  in  both  the  compile  and  evaluation  environments. 
The  get-operation- descriptor  function  and  all  the  macros  that  use  it 
depend  upon  this  assumption. 

It  is  an  error  to  make  an-operation-descriptor  with  a  non-7u7  ty_type 
if  ty_type  is  the  ancestor  of  any  other  type.  Thus  all  the  oj)eration 
descriptors  for  a  type  must  be  made  before  the  type  is  made  a 
parent  of  another  type. 

INDEXING:  An- operation- descriptor  may  be  indexed  by  a  lias-name  operation  in  the  nor¬ 
mal  way.  It  is  also  referenced  by  a  variety  of  indices  which  enable  the  search 
described  above.  Just  before  indexing, 

{execute-found-operation 

{find- operation- descriptor  nil  index-operation-descriptor  ty_type) 
index-operation-descriptor  opd^descriptor  ty_type) 

is  executed  if  the  call  to  find- operation- descriptor  returns  non-ni7.  The  value 
returned  by  this  operation  replaces  opd_descriptor  as  the  value  to  be 
returned  by  the  descriptor  making  operation.  This  value  is  the  descriptor 
that  is  indexed,  provided  it  is  not  a  stub  and  has  never  been  indexed  before. 
The  returned  value  may  be  a  stub,  or  any  operation  descriptor,  either  previ¬ 
ously  indexed,  or  never  before  indexed. 
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(s_attribute  ’ob_object  .)  [SKETCH  Attribute  MacTo| 

(s.attribute  (s«type  ob.object  )  ..)  [SKETCH  Attribute  Macro- 

WHERE:  S^attribiite  is  the  name  of  some  SKETCH  attribute,  at_attribute:  e  g.  has- 
name,  has-func lions, 

RETURNS:  The  value  of  the  attribute  labeled  at_attribute  for  ob_object.  If  the  attribute 
has  never  been  assigned  a  value  for  the  object,  nil  is  returned. 

WHEN  SETF:  The  value  of  the  attribute  is  changed. 

EFFICIENCY:  The  form  with  (s_type  ob_object  ...)  rather  than  just  ob_object  is  often 
more  efficient  when  compiled,  because  s_type  tells  the  compiler  the  type  of 
ob_object. 

NOTE:  By  default,  attributes  can  be  initialized  but  not  seif.  Attributes  that  are  other¬ 
wise  are  marked  as  such  in  documentation. 

Attributes  can  be  declared  to  have  non-standard  behaviors  for  certain  types  of 
object,  and  such  behaviors  will  be  documented. 

EQUIVALENT  TO:  {get-a(tribxi(e  s^attribute  ob_object  ...) 


However,  it  is  permissible  to  override  this  definition  by  setting  the 
function  definition  of  s_attribute.  The  default  macro  definition  of 
s_attribute  will  not  replace  an  existing  definition. 

NOTE:  All  symbols  beginning  with  an  auxiliary  verb  (has,  is,  do,  etc.)  or  preposition  fol¬ 
lowed  by  a  hyphen  should  name  SKETCH  attributes,  and  all  SKETCH  attributes 
should  have  names  beginning  with  such  prefixes. 


(a-type  lias-name  ’s_name 
[/las-size  \\_sizej 
[lias-parameters  ’g_parameters) 
[has-iufo  *g_infoj 
[lias-parent  ’ty_parentj) 

a-type 

ty- 

(has- attribute-descriptors  'ty_type) 
(has-operat ion-descriptors  ’ty_type) 
(has-allocation-count  ’ty_type) 
(has-children  ’ty_type) 

(has-size  Ty_type) 

(has-parameters  ’ty_type) 

(has-info  ’ty_type) 

(has-parent  ’ty_type) 

USE:  A-type  is  the  type  of  SKETCH  objects, 
and  so  is  {has-type  a-type). 


[SKETCH  Type  Macroj 


[SKETCH  Type) 
[SKETCH  Argument  Prefix] 
[SKETCH  Attribute  Macro] 
[SKETCH  Attribute  Macro] 
[SKETCH  Attribute  Macro] 
[SKETCH  Attribute  Macro] 
[SKETCH  Attribute  Macro] 
[SKETCH  Attribute  Macro] 
[SKETCH  Attribute  Macro) 
[SKETCH  Attribute  Macro] 

E.g.,  {has-type  an-attribute)  is  eq  a-type 


ARGUNfENT  PREFIX:  Arguments  with  the  ty_  prefix  are  a-type  values. 

HAS-NAME:  Type  objects  MUST  have  a  name  beginning  with  a-  or  an-:  e  g.,  an- 
operation.  See  lias-name 
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HAS-SIZE:  The  size  in  bits  of  a  datum  of  this  type  when  it  is  an  element  of  a  vector  or 
array.  Nil  if  unknown  or  not  useful. 

HAS-PARAMETERS:  Parameters  for  use  by  the  operations  on  objects  of  the  type.  May  be 
self. 

HAS-INFO:  Just  like  has- par  am  tiers  but  is  not  visible:  is  not  printed  or  represented  in  the 
unevaluated  type  object.  Useful  for  cross  reference  lists. 

HAS-PARENT:  Another  type  used  in  place  of  this  type  if  this  type  does  not  have  some 
operation  or  attribute  descriptor  that  is  needed.  E.g.,  this  type  inherits 
operations  such  as  create-objtci  from  its  parent. 

A  type's  parent,  its  parent's  parent,  etc.  are  the  ancestors  of  a  type.  A 
type  inherits  all  the  attribute  descriptors  and  operation  descriptors  of  its 
ancestors  (see  an-attribiite-descriptor  and  an-operafion-descriptor). 

HAS-.ALLOCATION- COUNT:  The  number  of  objects  of  this  type  that  have  been  created. 

If  nilj  this  count  is  not  maintained.  Code  that  does  not  main¬ 
tain  this  count  can  be  slightly  more  efficient  than  code  which 
does. 

Defaults  to  nil.  If  initialized  to  any  wow-nil  value,  the  value  0 
will  be  substituted  for  the  initial  value.  If  initialized  to  a 
wow-nil  value  in  the  compiler  environment,  must  be  initialized 
to  a  non-rzj7  value  in  the  evaluator  environment. 

Can  be  self. 

HAS-ATTRIBUTE-DESCRIPTORS:  A  list  of  the  heads  of  all  the  attribute  descriptor  groups 

for  this  type  (these  are  the  groups  labeled  by  1  in  the 
documentation  of  an-attribiite-descriptor).  Cannot  be 
initialized. 

HAS-OPERATION-DESCRIPTORS:  A  list  of  the  heads  of  all  the  operation  descriptor  groups 

for  this  type  (these  are  the  groups  labeled  by  1  in  the 
documentation  of  an-operation-descriptor).  Cannot  be 
initialized. 

HAS-CHILDREN:  A  list  of  all  the  other  types  whose  parents  are  this  type.  Cannot  be  ini¬ 
tialized. 

ORDER  OF  MAKING:  All  attribute  descriptors  and  operation  descriptors  for  a  type  must 
be  made  before  the  type  is  made  a  parent  of  any  other  type. 

INDEXING:  Whenever  a  type  is  indexed,  the  name  of  the  type  has  its  function  definition 
set  if  it  was  previously  nil.  This  is  also  done  for  stubs,  as  sometimes  a  stub  is 
a  completely  defined  type  (it  will  cease  to  be  a  stub  when  operation  or  attri¬ 
bute  descriptors  are  associated  with  it).  See  s^fype. 


Printed  April  27,  1989 


OBJECTS 


5-43 


(a-vector-element-C-type  has-parent-type  'cy_parent-type)  [LISP  Function] 

\has-C-type-JoTinat  (g_C-type-format-part-l  ...)| 

\has-C-typc-repeat-forinut  (g_C-type-repeat-format-part-l  ...)| 

has-sxzt  x_3ize 

has- alignment  x_alignment 

[has-initial-value  g_initial- value] 

has-get-function  s_get-function 

has-get-macro  s_get-macro 

has- set- function  s_set-function 

has-set-macro  s_set-macro 

\has-parameter$  g_parameters] 

[has-irifo  g_info|) 


a-vector-element-C-type 

veCty_ 

(has-parent-type  VeCty^type) 
(has-C-type-format  ’veCty_type) 

(has-C- type- repeat-format  VeCty_type) 
(has-size  VeCty^type) 

(has-alignment  VeCty_type) 
(has-initial-value  VeCty_type) 

(has-get- function  VeCty_type) 
(has-get-macro  ’veCty_type) 
(has-set-function  ’veCty_type) 
(has-set-macro  ’veCty_type) 
(has-paramters  ’veCty_type) 

(has-info  VeCty_type) 


[SKETCH  type] 
[Argument  Prefix] 
[SKETCH  Attribute  Macro] 
[SKETCH  Attribute  Macro] 
[SKETCH  Attribute  Macro] 
(SKETCH  Attribute  Macro] 
[SKETCH  Attribute  Macro] 
[SKETCH  Attribute  Macro! 
^SKETCH  Attribute  Macro] 
[SKETCH  Attribute  Macro] 
[SKETCH  Attribute  Macro] 
[SKETCH  Attribute  Macro) 
[SKETCH  Attribute  Macro] 
[SKETCH  Attribute  Macro] 


USED  ONLY  WHEN:  Defining  new  C  data  types  for  inclusion  in  declare-vector-type  defined 
objects. 


USE:  A-vector- element- C- type  defines  a  C  data  type  that  can  be  used  for  elements  of 
declare-vector-type  defined  objects.  Such  a  C  data  type  corresponds  to  a-type 
object  which  has  a  has-vector-elenient-C-type  attribute  that  is  a-vector-element-C- 
type  with  descriptive  information.  The  a-type  object  is  used  to  denote  the  resulting 
type.  Examples  are  a-char  and  a-short. 

ARGUMENT  PREFIX:  Arguments  with  the  veCty^  prefix  must  be  a-vector-element-C-type 
values. 


HAS-PARENT-TYPE:  This  is  the  a-type  object  used  to  denote  the  a-vector-elcment-C-type 
object.  The  latter  is  the  has-vector-element-C-type  attribute  of  the 
former. 

HAS-C- TYPE-FORMAT: 

HAS-C- TYPE-REPEAT-FORMAT:  ’(g_type-format-part- 1  ...)  is  a  list  of  elements  which  may 

be  patom'ed  to  declare  a  variable.  The  symbol  NAME  in 
this  list  is  replaced  by  the  name  of  the  variable.  No  semi¬ 
colon  or  carriage  return  should  be  included. 


An  example  is— 
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(bhort,  I  name:) 

for  a-sliort. 

HaS’C’type-repeat-format  is  the  same  thing,  but  is  used  in 
case  there  is  an  x_repeat-count  (see  declare-vector-hjpe). 
The  symbol  REPEAT  is  replaced  by  the  repeat  count. 
For  example— 

(|xxx_alloc  (I  NAME  |,  |  REPEAT  |)D 

for  a  structure  allocated  by  the  xxx_alloc  macro  with  a 
required  repeat  count  (see  C  CODE  SIDE  EFFECTS 
under  dcclart-vcctor-typt). 

An  expression  which  is  itself  a  list  may  be  on  element  of 
these  format  lists,  in  which  case  the  expression  is  not 
patom^td,  but  rather  is  evaPed  with  NAME  bound  to  the 
variable  name  and  REPEAT  to  the  repeat  count,  and  the 
result  is  patom'td. 

The  symbol  REPEAT  is  also  recognized  in  bas-C-type- 
format  and  replaced  by  1.  If  bas-C-hjpe-repeat-forwat  is 
ni7,  haS’C’type-format  will  be  used  in  its  place. 

The  has-C-type-format  and  has-C-type-repeat-formai  are 
currently  unused  if  the  lias-size  attribute  is  less  than  8.  as 
the  C  language  requires  special  treatment  for  fields. 

HAS-SIZE:  X_size  is  the  number  of  bits  in  the  element.  This  must  be  an  integer  above  0. 

HAS-ALIGNMENT:  X_alignment  is  a  number  which  must  exactly  divide  the  displacement 
of  the  element  in  bits  within  any  vector.  It  must  equal  I,  2,  4,  8,  16, 
32,  or  64.  X_size  must  be  an  exact  multiple  of  x_alignment. 

If  x^ize  is  less  than  8,  then  it  must  equal  x_alignment.  If  x_size  is  8 
or  greater,  then  so  must  be  x_alignment. 

HAS- INITIAL- VALUE:  The  initial  value,  g_initial-value,  may  be  stored  into  the  vector 
using  the  s^et-function  to  get  a  default  initial  value  appropriate  for 
the  element. 

HAS-GET-FUNCTION: 

HAS-GET-MACRO:  S_get-function  and  s_get-macro  may  be  used  to  return  the  value  of  the 
element  in  a  vector.  The  calls  are— 

(/unca// s_get-function  veCt_type  x_index  V_vector  ...) 

and 

(s_get-macro  veCt_type  .\_index  V_vector  ...) 

where  veCt_type  is  the  vector-element-C-type  object  in  which  s_get- 
function  or  s^et-macro  was  found,  x_index  is  the  displacement  of  the 
element  within  V.vector  measured  in  units  of  x.alignment  bits, 
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V^vector  is  the  immediate  vector  containing  the  element,  and  .  are 
any  extra  arguments  that  might  be  of  use  in  selecting  part  of  the  ele¬ 
ment,  instead  of  the  whole  element.  The  veCt.type  argument  to  this 
macro  is  pre-evaluated. 

HAS-SET-FUNCTION: 

HAS-SET- MACRO:  S^et-function  and  s^et-macro  may  be  used  to  return  the  value  of  the 
element  in  a  vector.  The  calls  are— 

(/unca// s_set-function  g^value  veCt_type  xjndex  V_vector  ...) 

and 

(s_set-macro  g_value  veCt_type  x_index  V_vector  ...) 

where  g_value  is  the  value  to  be  stored,  veCt_type  is  the  vector- 
element-C- type  object  in  which  s^et-function  or  s_sel-macro  was 
found,  x_index  is  the  displacement  of  the  element  within  V_vector 
measured  in  units  of  x_alignment  bits,  V_vector  is  the  immediate  vec¬ 
tor  containing  the  element,  and  ...  are  any  extra  arguments  that  might 
be  of  use  in  selecting  part  of  the  element,  instead  of  the  whole  element. 
The  veCt_type  argument  to  this  macro  is  pre-evaluated. 

HAS-P.AR.AMETERS: 

HAS-INFO:  These  attributes  are  parameters  for  s_get-function,  s_get-macro.  s_set- 
function,  and  s_set-macro.  The  has-parameters  attribute  is  visible,  and  the 
lias-hifo  attribute  hidden:  otherwise  there  is  no  difference. 

Both  of  these  attributes  can  be  self. 

NOTE:  When  included  in  declare-vector-type  objects,  an  element  may  be  included  in  both 
the  vector  and  the  hunk  part  of  the  object.  If  this  is  done,  it  is  not  i)ermitted  to 
set  parts  of  the  element,  although  parts  can  be  read.  It  is  important,  in  this  case, 
that  the  the  copy  of  the  element  stored  in  the  hunk  be  read-only,  like  a  number, 
as  it  may  be  shared:  no  attempt  is  made  to  copy  it. 

(compare-object  ’ob_object-l  *ob_object-2)  [SKETCH  Operation  Macro] 

(compare-object-function  ’ob_object-l  ’ob_object-2)  [LISP  Function] 

compare-object  [SKETCH  Operation) 

RETURNS:  Non- ruV  if  ob_object-l  equals  ob_object-l.  Otherwise  iiii 

Compare-object  and  compare-object-function  do  the  same  things,  except  the 
first  is  a  macro  with  in-line  optimizations,  and  the  second  is  a  function  with 
no  optimizations.  However,  the  second  can  be  used  as  a  has- compare- switch 
value,  and  in  other  places  where  only  a  function  will  do. 

Compare-object  is  the  same  as  equal  when  comparing  numbers,  strings,  sym¬ 
bols,  ports,  and  lists.  Other  objects  are  equal  if  the  object  types  are  eq  and 
all  the  object  attributes  compare  equal  according  to  their  has-cotnpar e-switch 
values.  If  no  explicit  has- comp  are- switch  value  is  given  for  an  attribute,  or 
the  value  is  given  as  yes,  then  the  two  attribute  values  are  tested  by  equal.  If 
the  switch  has  the  value  no  the  attributes  are  not  tested  at  all.  If  the  switch 


Printed  April  27,  1989 


OBJECTS 


5-46 


has  some  other  symbol  as  a  value,  that  symbol  is  used  in  place  of  equal  to  test 
the  attribute  values  for  equality.  See  HAS-COMPARE-SWITCH  under  an- 
attribute-descriptor. 

Non-standard  equality  tests  may  also  be  defined  for  any  object  type. 

WARNING:  Equal  considers  a  fixnum  and  a  flonum  to  be  unequal,  even  if  they  have  the 
same  value.  E.g.,  1  does  not  equal  1.0. 

EFFICIENCY:  This  macro  compiles  more  efficient  code  if  ob_object-l  or  ob_object-2  is 
either  a  literal  or  an  expression  of  the  form— 

(s.type  ...) 

whose  type  s_type  is  specified  at  compile  time. 


The  code  to  test  equality  of  numbers,  strings,  symbols,  lists,  and  ports  is 
compiled  in-line. 


(create-object  ’{ty_type  at_attribute  g_value  ...) 
[’ob_prototype]) 

(create-parent-object  ’opd_descriptor 

^(ty^type  at_attribute  g_value 


create-object 


[SKETCH  Operation  Macro] 


[LISP  Macro] 

...)  j’ob_prototypej) 

[SKETCH  Operation] 


USE  ONLY  WHEN: 


Create-parent-object  is  used  only  when  defining  non-standard 
SKETCH  types. 


EQUIVALENT  TO:  Make-object  and  make-parent-object,  except  that 


(1)  Stubs  are  not  handled. 

(2)  Objects  returned  are  not  indexed. 

(3)  Default  values  are  not  added  to  the  at_attribute/g_value  list  if 
ob_prototype  is  nil. 

(4)  Has-init- function's  and  has- init- macrons  are  not  invoked. 

It  is  possible  to  get  the  effects  mentioned  in  (3)  and  (4)  by  applying 
process- attributes  or  process-attributes-for-macro  to  the  first  argument 
before  calling  create-object. 


Printed  April  27,  1989 


OBJECTS 


5-47 


(declare-hunk-type  (s^type  [s_C-type  s_G-prefix])  jLlSP  Macro] 

[s^attribute- visibility  I 
[has-is-a-stnb-stuitch  s_is-a-stub-switchj 
[has-compare-switch  s_compare-s witch] 

[has- format- switch  sjormat-switchj 
[has-uncval-switch  s_uneval-switch] 

[s^attribute-protection]  [has-password  s_password| 

[has- allocation-count  g_allocation-count] 
s_attribute-l 

(s_attribute-2  g_default-value-2  [s_C-attribute-name-2)) 

•••) 

(define-hunk-type  (list  ’ty^type  [’s_C-type  ’s_C-prefix|)  [LISP  Function] 

[’at_attribute- visibility] 

[lias-is-a-stub-switch  ’s_is-a-stub-switch] 

[has-compare-switch  ’s_compare-switch] 

[has-format-switch  ’s_format-switch] 

[has-uneval- switch  ’s^uneval-switchj 
[’at^attribute-protection]  [has-password  ’s_password] 
[/ia5-a//oca/ion-couri/  ’g_allocation-count] 

■at_attribute-l 

(list  ’at_attribute-2  ’g_default-vahie-2  [’s_C*attribute-naine‘2]) 

...) 

*C-definition-code-port*  [LISP  Global  Variable] 

WHERE:  Declare -hunk- type  and  define- hunk- type  take  substantially  the  same  arguments 
and  do  the  same  thing,  except  that  the  first  is  a  macro  that  does  not  evaluate 
its  arguments,  and  the  second  is  a  function  that  does.  For  the  macro,  types 
and  attributes  are  specified  by  their  symbol  names,  whereas  for  the  function, 
the  types  and  attributes  themselves  may  be  given.  The  function  will  accept 
stubs  of  types  and  attributes,  and  will  also  accept  symbols  naming  types  and 
attributes,  making  the  stubs  itself. 

If  s_C-type  and  s_C-prefix  are  omitted,  (s_type)  may  be  abbreviated  to  s_type 
and  (list  ’ty_type)  may  be  abbreviated  to  ’ty_type.  Similarly  s_attribute-l 
abbreviates  (s_attribute-l),  and  ’at_attribute-l  abbreviates  (list  ’at_attribute- 
1). 


For  define- hunk- typCj  in  what  follows,  s_type,  s_attribute-visibility, 
s_attribute-protection,  s_attribute-l,  and  s_attribute-2  are  the  names  of 
ty^type,  at^attribute- visibility,  at_attribute-protection,  at_attribute-l,  and 
at«attribute-2. 

The  arguments  consist  of  options  (s_attribute-visibility,  s_is-a-stub-switch, 
s_compare-switch,  sJ*or  mat-switch,  s_uneval-switch,  s_attribute-protection, 
and  s_password,  and  g_allocation-count)  and  attributes.  The  options  may  be 
listed  in  any  order,  and  may  be  repeated.  Each  option  applies  to  all  attributes 
following  it,  and  supercedes  any  previous  option  of  the  same  kind. 
G«allocation-count  is  an  exception,  and  should  appear  at  most  once. 
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S_attribute-visibility  specifies  the  print  and  uneval  characteristics  of  attributes 
following  it.  The  possible  values  of  s_attribute-visibilit.y  are— 


is-visible 

Include  in  all  comparc-object  tests,  pretty-prinCs,  and 
uncval-objccCs,  This  is  the  default  effective  at  the  begin¬ 
ning  of  the  argument  list.  Equivalent  to  has-comparc- 
switch  nil,  has- format- switch  nil,  and  has-uncval-switcli  nil. 

Is-hidden 

Do  not  include  in  cojiip are- object  tests,  uneval-objecCs,  or 
pretty-prinfs.  Equivalent  to  has-compare-switch  no,  has- 
format-switch  no,  and  lias-xineval- switch  no. 

It  is  also  possible  to  specify  the  compare,  format,  and  uneval  switches  more 
e.xplicitly  using  the  has-compare-switcli,  has-forinat-switch,  and  lias-uneval- 
switcli  options.  These  are  useful  for  specifying  function  names  for  these 
switches:  see  an-attributc-dcscriptor. 

S_attribute-protection  specifies  the  protection  of  all  the  attributes  following  it, 
and  is  one  of— 


is-read-init 

Readable  by  everyone,  but  not  writable.  Can  be  ini¬ 
tialized.  This  is  the  default  effective  at  the  begin¬ 
ning  of  the  argument  list. 

is-read-in  it- write 

Readable  and  writable  by  everyone.  Can  be  initial¬ 
ized. 

is- private 

Readable  and  writable  only  by  calls  of  the  form 

(s_attribute  ob_object  s_password  ...) 

that  contain  s^password  as  the  second  argument. 
Cannot  be  initialized  (i.e.,  will  always  be  initially  set 
to  the  default  value). 

is- read- private 

Readable  by  everyone,  but  writable  only  by  calls 
that  contain  s_password  as  the-second  argument. 
Cannot  be  initialized  (i.e.,  will  always  be  initially  set 
to  the  default  value). 

is-read-init-private 

Readable  by  everyone,  but  writable  only  by  calls 
that  contain  s_password  as  the-second  argument. 
Can  be  initialized. 

The  has-password  option  specifies  the  password,  s_password,  to  be  used  by  all 
private  attributes  following  this  option. 

S^password  will  be  made  into  a  global  constant,  and  should  follow  the  naming 
conventions  for  such  (have  at  the  beginning  and  end). 
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The  default  value  of  g_allocation-coiint  is  non-/n7,  which  enables  maintenance  of 
the  has- allocation- count  attribute  of  s_type.  This  attribute  counts  the  number 
of  objects  of  type  s_type  which  have  been  created.  A  value  of  nil  disables 
maintenance  of  the  attribute. 

An  attribute  may  be  specified  either  by  a  single  s_attribute  label,  or  by  a  list 
(s_attribute  g_default-value  [s_C-attribute-name))  in  which  the  default  value  is 
an  expression  not  referencing  local  variables  which  is  to  be  evaluated  and  used 
as  the  value  of  the  s^attribute  attribute  whenever  a  new  object  of  type  s_type  is 
made  and  no  explicit  value  is  given  for  the  attribute.  Giving  a  default  value  of 
nil  is  the  same  as  giving  no  default  value  at  all. 

S_C-type,  s_C-prefix  and  s_attribute-name-2  are  symbols  used  to  generate  C 
code,  see  C  CODE  SIDE  EFFECTS  below. 

RETURNS:  The  a-type  object  made. 

SIDE  EFFECTS:  Makes  a-typc  named  s_type  whose  objects  are  hunks  with  attribute  ele¬ 
ments  s_attribute-l  ....  An-attribute  objects  named  s_attribute-l  ...  are 
also  made  if  they  do  not  previously  exist. 

An- attribute- descriptor  is  made  for  s_type  and  each  s_attribute-l ,  An- 
operation- descriptor  is  made  for  s_type  and  the  each  of  the  following 
operations:  make-object^  create-object^  object-is,  object- is-a-stub, 

compare-object,  move-object,  uneval-object,  format-object. 

The  attribute  elements  specified  in  the  call  to  declar e-hunk- type  are  ele¬ 
ments  of  hunks  and  are  very  quickly  accessible  by  indexing  (cxr).  In 
addition,  any  other  attributes  not  specified  in  the  call  to  declare-hunk- 
type  or  define- hunk- type  may  be  set  for  an  object  of  type  s_type,  but 
these  will  be  put  on  a  property  list  for  the  object,  and  will  not  be 
accessed  as  efficiently. 

A  [defvar  s_password  ’s_password)  is  generated  for  each  password.  It  is 
important  that  a  password  evaluate  to  itself,  so  that  s_password  can  be 
used  as  an  argument  to  both  macro  and  function  calls. 

C  CODE  SIDE  EFFECTS:  If  the  global  variable  *C-definition-code-port*  is  non-nil,  if  s_C- 

prefix  is  non-nil,  and  if  *in-environment*  is  nil  (we  are  not  being 
loaded  by  an  environment  statement),  then  a  structure  definition 
will  be  written  into  *C- definition- code-port*  (which  must  be  a- 
port).  This  structure  definition  will  have  the  form  — 
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typedef  struct  <s_C-pvtf\x> struct  *  <s_C-type>; 
struct  <s_G- prefix  { 

sat_lcalue  <s_C-prefix>plist; 
sob_typc  <s_C-prefix>type; 

sat_lvalue  <s_C-attribute-name-2>; 

i^dcfinc  <s_C-prefix>a//oc(x,y)  struct  <sJ3-pTei\x> struct  (x)  [y] 

where  the  exact  order  of  the  structure  element  definitions  will  be 
implementation  dependent. 

NOTE:  Dcclarc-hunk-iype  expands  into  a  call  to  dc fine-hunk- type  nested  inside  an  eval- 
when  {compile  eval  load). 

NOTE:  Attribute  and  operation  descriptors  can  be  made  for  a  hunk  type  after  the  call  to 
declare-hunk-type  or  define- hunk- type  that  makes  the  type.  If  a  new  descriptor  is 
for  an  attribute  or  operation  declared  by  the  execution  of  declare-hunk-type  or 
define- hunk- type,  the  descriptors  declared  by  that  e.xecution  will  become  ances¬ 
tors  of  the  new  descriptor. 

NOTE:  A  call  to  declare- htnik- type  or  define-hunk-type  may  be  repeated  more  than  once. 
Only  the  first  call  will  make  or  change  anything.  Subsequent  calls  will  merely 
test  that  they  are  essentially  identical  to  the  first  call,  and  complain  if  they  are 
not. 

NOTE:  The  compare-object,  object- is- a- stub,  format-object,  and  uneval-object  functions 
defined  by  declare-hunk-type  or  define-hunk-type  use  only  the  attributes  actually 
stored  in  the  objects,  and  get  these  attributes  using  the  functions  and  macros 
defined  by  declare-hunk-type  or  define-hunk-type.  Attribute  descriptors  not 
defined  by  declare-hunk-type  or  define-hunk-type  are  ignored  for  the  purposes  of 
getting  these  attributes.  However,  these  latter  attribute  descriptors  are  not 
ignored  for  purposes  of  getting  the  necessary  switchs:  has- compare-switch,  has- 
is-a-stub-switch,  has- format- switch,  and  has- uneval- switch. 

All  attribute  descriptors  that  provide  switches  for  an  object  of  a  given  type 
should  be  defined  before  the  first  object  of  that  type  is  created.  This  is  because 
optimizing  information  for  performing  operations  such  as  format-object  is  com¬ 
puted  at  that  time. 

IMPLEMENTATION:  The  current  implementation  (which  is  subject  to  change)  uses  hunks 
that  have  two  more  elements  than  the  number  of  attributes.  The 
first  two  elements  are  used  as  the  first  cell  of  a  disembodied  property 
list.  The  object  type  is  stored  in  the  first  element  of  the  hunk,  and  a 
pointer  to  the  first  attribute  label  on  the  property  list  is  stored  in  the 
restl  element  of  the  hunk.  The  attributes  s_attribute-l,  ...  are 
assigned  to  hunk  elements  with  indices  2,  3,  ...,  in  the  order  in  which 
the  attributes  appear  as  arguments  to  declare-hunk-type. 

Attributes  made  for  a  hunk  type  after  the  execution  of  declare- 
hunk-type  or  define-hunk-type  will  not  be  assigned  to  elements  of  the 
hunk,  But  will  be  put  on  the  property  list. 
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(declare-vector-type  (s_type  [s_C-type  s_C-prefix]) 


LISP  Macro] 


[has-allocation’ count  g_allocation-coimt| 

\has-C-type-vector- element- name  s_C-type-vector-element-name| 

[has- C-plist- vector- element-najiie  s_C- pi ist- vector-element- name] 
\has-C‘Vsize-vector-element-name  s_C-vsize-vector-element-name| 
\has-pointer-C-type  s_pointer-C-type] 

[has-allocate-C-type  s_allocate-C-type| 

(s_at tribute- type]  (s_attribute- location]  [s_attribute- visibility] 
[has-is-a-stub’Switch  s_is-a-stub-switch] 

[has- compare-switch  s_compare-switch] 

[has-format-switch  s_for mat-switch] 

[has-uneval- switch  s_uneval- switch] 

[s_attribute-protection]  [has-password  s_password] 

[x_repeat-count]  s_attribute-l 

[x_repeat-count]  (s_attribute-2  g_(lefault-value-2  [s_C-attribute-name-2]) 
(define-vector-type  {list  *s_type  ps_C-type  *s_C-prefiN])  ’LISP  Function] 


[has- C- type-vector- elemerit-name  ’s_C-type-vector-element-name] 
[has- C-pli$t- vector- element-name  ’s_C-plist-vector-element-name] 
[has-C-vsize-vector-element-nanie  ’s_C-vsize-vector-element-name] 
[has-pointer-C-type  ’ty_pointer-C-type] 

[has- allocate- C- type  ’ty_allocate-C-type] 


[’ty_attribute-type]  [’at_attribute-location]  pat_attribute- visibility] 
[has-is- a-stub-switch  ’s_is-a-stub-switch] 

[has- compare-switch  ’s_compare-switch] 

[has-format-switch  ’s_for mat- switch] 

[has-uneval- switch  ’s_uneval-switch] 

[’at_attribute-protection]  [has-password  's_passworcl] 

[has- allocation- count  ’g_allocation-count] 


px_repeat-count]  ’at_attribute-l 
(Lx_repeat-count]  (list  ’at_attribute-2 

•••) 


’g«default-value-2 

[*s_C-attribute-name-2]) 


*C-definition-code-port*  [LISP  Global  Variable] 

(has- vector- type  ’ty_type)  [SKETCH  Attribute  Macro] 

WHERE:  Declare-vector-type  and  define- vector- type  take  substantially  the  same  argu¬ 
ments  and  do  the  same  thing,  except  that  the  first  is  a  macro  that  does  not 
evaluate  its  arguments,  and  the  second  is  a  function  that  does.  For  the  macro, 
types  and  attributes  are  specified  by  their  symbol  names,  whereas  for  the  func¬ 
tion,  the  types  and  attributes  themselves  may  be  given.  The  function  will 
accept  stubs  of  types  and  attributes,  and  will  also  accept  symbols  naming  types 
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and  attributes,  making  the  stubs  itself. 

If  s_C-type  and  s_C-prefix  are  omitted,  (s_type)  may  be  abbreviated  to  s_type, 
and  (list  ’ty_type)  may  be  abbreviated  to  ’ty_type.  Similarly  s_attribute-l 
abbreviates  (s_attribute-l),  and  ’at_attribute-l  abbreviates  (list  ’at_attribute- 
1). 

For  dejine-vector-typc,  in  what  follows,  s_type,  s_pointer-C-type,  s_allocate-C- 
typc,  s«attribute-type,  s^attribute-location,  s_attribute-visibility,  s_attribute- 
protection,  s_attribute-l,  and  s_attribute-2  are  the  names  of  ty_type, 
ty_pointer-C-type,  ty«allocate-C-type,  ty_attribute-type,  at^attribute-location, 
at_attribute-visibility,  at_attribute-protection,  at_attribute-l,  and 
at_attribute-2. 

The  arguments  consist  of  options  (s_C-type-vector-element-name,  s_C-plist- 
vector-element-namc,  s_C-vsize-vector-element-name,  s_pointer-C-type, 
s_allocate-C-type,  s_attribute-type,  s_attribute-location,  s_attribute-visibility, 
s_is-a-stul>switch,  s_compare-switch,  s_format-switch,  s«uneval-switch, 
s_attribute-protection,  s^passworcl,  and  g_allocation-count)  and  attributes. 
Most  options  may  be  listed  in  any  order,  and  may  be  repeated.  Each  option 
applies  to  all  s_attribute’s  following  it,  and  supercedes  any  previous  option  of 
the  same  kind.  S_C-type-vector-element-name,  s_C-plist-vector-element-name, 
s_Ovsize-vector-element-name,  s_pointer-C-type,  s_allocate-C-type,  and 
g_allocation-count  are  exceptions,  should  appear  at  most  once,  and  must  appear 
before  other  arguments. 

Dectare-vector-type  and  dcfine-vector-type  define  a  type  named  s_typesuch  that 
objects  of  that  type  are  represented  by  the  combination  of  an  immediate  vector 
and  a  hunk.  Attributes  may  be  assigned  to  either  the  vector  or  the  hunk  or 
both. 

Attributes  that  hold  pointers  may  be  of  type  a-value.  A-value  attributes  are 
usually  assigned  to  both  the  vector  and  the  hunk.  They  are  assigned  to  the  vec¬ 
tor  so  they  will  be  readily  available  to  C  functions,  which  are  given  a  pointer  to 
the  vector  when  called  with  the  object  as  a  parameter,  and  they  arc  assigned  to 
the  hunk  so  the  garbage  collector  will  know  about  them. 

Other  attributes,  such  as  numeric  ones,  are  commonly  assigned  only  to  the  vec¬ 
tor,  and  arc  stored  as  numbers  proper,  and  not  as  pointers.  However,  the  value 
nil  may  also  be  stored  for  signed  numeric  types  by  representing  it  as  a  special 
missing  value. 

S_attribute-type  specifies  the  type  of  the  attributes,  and  may  be  one  of  the  fol¬ 
lowing— 
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Number  of  Bits 

1 

8 

16 

32 

64 

aii’lbit 

a-ubit 

a-uchar 

a-char 

a-ushort 

a-short 

a-ulong 

Q-long 

art-ini 

an-un$igned 

Q-float 

a-value 

a-double 

When  a  value  of  one  of  these  types  is  stored  in  the  immediate  vector,  it  is 
packed  according  to  the  associated  C  type  (the  C  type  associated  with  a-valuc  is 
sat^lvaluCf  and  the  C  type  associated  with  either  an-lbitov  a-^ibit  is  unsigned:!). 

A-value  is  the  default  attribute  type  effective  at  the  beginning  of  the  argument 
list. 

Additional  types  can  be  allowed  as  vector  elements  by  defining  a-cector- 
elenient-C-type  object  describing  them.  Also  see  s_pointer-C-type  and 
s_allocate-C-type  below  (under  C  CODE  SIDE  EFFECTS).  Types  for  which 
this  has  not  been  done  can  still  be  used  as  in-liunk  elements  (see  next  para¬ 
graph). 

S_attribute- location  is  one  of  the  following— 


in-vector 

Assign  to  the  immediate  vector  only. 

in-hunk 

Assign  to  the  hunk  only. 

in-one 

Assign  a-value  attributes  to  the  hunk  and  other  attributes 
to  the  immediate  vector. 

in-default 

Assign  a-value  attributes  to  both  the  immediate  vector  and 
the  hunk,  and  other  attributes  to  the  immediate  vector 
only.  This  is  the  default  attribute  location  effective  at  the 
beginning  of  the  argument  list. 

in-both 

Assign  attributes  to  both  the  immediate  vector  and  the 
hunk. 

S^attribute-visibility  specifies  the  print  and  uneval  characteristics  of  attributes 
following  it.  The  possible  values  of  s^attribute-visibility  are— 
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is-visible 

Include  in  all  compare-object  tests,  pretty-print's,  and 
uneval- object^ s.  This  is  the  default  effective  at  the  begin¬ 
ning  of  the  argument  list.  Equivalent  to  has- compare- 
switch  nil,  has- for  mat- switch  nil,  and  has-uneval-switch  nil. 

is-hidden 

Do  not  include  in  compare-object  tests,  uneval-objecCs,  or 
pretty-prinCs.  Equivalent  to  has-compare-switch  no,  has- 
format-switch  no,  and  has-uneval-switch  no. 

It  is  also  possible  to  specify  the  compare,  print,  and  uneval  switches  more  expli¬ 
citly  using  the  has-compart-swiich,  has- format- switch,  and  has-uneval-switch 
options.  These  are  useful  for  specifying  function  names  for  these  switches:  see 
an- attribute- descriptor. 

The  is-a-stub  switch  can  similarly  be  specified  explicitly  by  has-is-a-$tub-swilch. 
This  switch  defaults  to  nil  and  is  not  affected  by  s_attribute-visibility. 

S_attribute-protection  specifies  the  protection  of  all  the  attributes  following  it, 
and  is  one  of— 


is-  read- in  it 

Readable  by  everyone,  but  not  writable.  Can  be  ini¬ 
tialized.  This  is  the  default  effective  at  the  begin¬ 
ning  of  the  argument  list. 

is- read-init- write 

Readable  and  writable  by  everyone.  Can  be  initial¬ 
ized. 

is- private 

Readable  and  writable  only  by  references  of  the 
form 

(s_attribute  ob^object  s_password  ...) 

that  contain  s_password  as  the  second  argument. 
Cannot  be  initialized  (i.e.  is  always  set  to  the  de¬ 
fault  value  on  initialization). 

is- read-private 

Readable  by  everyone,  but  writable  only  by  calls 
that  contain  s_password  as  the  second  argument. 
Cannot  be  initialized  (i.e.  is  always  set  to  the  de¬ 
fault  value  on  initialization). 

is- read- in  it- p  ri V  at e 

Readable  by  everyone,  but  writable  only  by  calls 
that  contain  s^password  as  the  second  argument. 
Can  be  initialized. 

The  has-password  option  specifies  the  password,  s_password,  to  be  used  by  all 
private  attributes  following  this  option. 

S_password  will  be  made  into  a  global  constant,  and  should  follow  the  naming 
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conventions  for  such  (have  at  the  beginning  and  end). 

The  default  value  of  g_allocation-count  is  non-nil,  which  enables  maintenance  of 
the  has- allocation- count  attribute  of  s_type.  This  attribute  counts  the  number 
of  objects  of  type  s_type  that  have  been  created.  A  value  of  nil  disables 
maintenance  of  the  attribute. 

An  attribute  may  be  specified  either  by  a  single  s^attribute  label,  or  by  a  list 
(s^attribute  g_default-value  [s_C-attribute-name])  in  which  the  default  value  is 
an  expression  not  referencing  local  variables  which  is  to  be  evaluated  and  used 
as  the  value  of  the  s^attribute  attribute  whenever  a  new  object  of  type  s_type  is 
made  and  no  explicit  value  is  given  for  the  attribute.  Giving  a  default  value  of 
nil  is  the  same  as  giving  no  default  value  at  all. 

An  attribute  may  have  a  repetition  count,  x_repeat-count.  provided  the  attri¬ 
bute  is  in  the  vector  but  not  the  hunk.  The  C  code  version  of  the  attribute  will 
get  the  dimension  specifier  ‘l.\_repeat-count]\  and  will  therefore  be  repeated  in 
the  vector  x_repeat-count  times. 

If  the  attribute  is  gotten  a  list  of  x_repeat-count  element  values  will  be 
returned,  and  such  a  list  may  be  written  to  the  attribute.  If  an  extra  argument 
x_N  is  supplied  to  the  attribute  access  expression,  the  x^N-fl’st  element  of  the 
x_repeat-count  elements  will  be  accessed.  E  g  — 

(s_attribute  V_object  x_N) 
accesses  the  x^N-hl’s  s_attribute  element  of  V_object. 

S_C-type,  s_C-prefix,  and  s_C-attribute-name  are  symbols  used  to  generate  C 
code:  see  C  CODE  SIDE  EFFECTS  below. 

Elements  less  than  8  bits  long  may  have  an  x_repeat-count,  but  any  s_C- 
attribute-name  will  refer  to  only  the  first  of  the  sequence  of  x_repeat-count  ele¬ 
ments,  as  C  does  not  support  vector  indexing  of  such  elements. 

RETURNS:  The  a-typc  object  made. 

SIDE  EFFECTS:  Makes  a-typc  named  s_type  whose  objects  are  immediate  vectors  with 
attribute  elements  s_attribute-l  ....  The  property  list  of  these  vectors 
begins  with  a  hunk  that  contains  additional  information  about  the 
object. 

An-attributc  objects  named  s_attribute-l  ...  are  also  made  if  they  do  not 
previously  exist. 

An-attributc- descriptor  is  made  for  s_type  and  each  s_attribute-l .  An- 
opcration-dcscriptor  is  made  for  s_type  and  each  of  the  following  opera¬ 
tions:  makc-objcct,  ^crcatc-objcctj  objcct-is,  objcct-is-a-stub,  compare- 
object^  move-object,  uneval- object,  format-object. 

The  attribute  elements  specified  in  the  call  to  declare-vector-type  are 


Printed  April  27,  1989 


OBJECTS 


5-56 


elements  of  vectors  and  hunks,  and  are  quickly  accessible  by  indexing  (see 
vrefi-xxx  and  cxr).  In  addition,  any  other  attributes  not  specified  in  the 
call  to  declarc-vector-typc  or  dcfinc-vector-type  may  be  set  for  an  object 
*  of  type  s_type,  but  these  will  be  put  on  a  property  list  for  the  object,  and 
will  not  be  accessed  as  efficiently. 

A  {dcfvar  s_password  ’s_password)  is  generated  for  each  password.  It  is 
important  that  a  password  evaluate  to  itself,  so  that  s^password  can  be 
used  as  an  argument  to  both  macro  and  function  calls. 

C  CODE  SIDE  EFFECTS:  If  the  global  variable  *C-dcfinition-codc-port*  is  non-nil,  if  s_C- 

prefix  is  non-m7,  and  if  *in-environment*  is  m7  (we  are  not  being 
loaded  by  an  environment  statement)  then  a  structure  definition 
will  be  written  into  *C- definition- code-port*  (which  must  be  a- 
port).  This  structure  definition  will  have  the  form— 

typedef  struct  <s_C-prefix> s/ruc/  *  <s_C-type>; 
struct  <s^C-pTef\x> struct  { 
union  { 

hit  SOB.VSIZE  (1); 
satjvalue  *  SOB.VPLIST  (l); 
sob^type  SOB.VTYPE;  }  SOB.VFIRST; 

#  define  <s_C-type-vector-element-name>  SOB_VFIRST.SOB_VTYPE 
define  <s_C-plist-vector-element-name>  SOB_VFIRST.SOB_VPLlST[-l][0] 
define  <s_C-vsize-vector-element-name>  SOB_VFIRST.SOB_VSIZE[-2] 

<C-attribute- type-1  >  <s_C- attribute-name-1  > ; 

#  define  <s_C-attribute-name-2>  SOB_VFIRST.SOB_VPLIST[-lj  [<x2>] 

}; 

if^define  <s_C-prefix>a//oc(x,y)  struct  <s_C-prefix (x)  [y] 

The  default  value  of  s_C-type-vector-element-name  is  <s_C- 
prefix>type  if  s_C-prefix  is  non-nil,  or  nil  otherwise.  If  s_C- 
type-vector-element-name  is  non-nil,  it  is  the  C  structure  element 
name  of  the  first  element  of  the  C  accessible  vector  which  is 
defined  to  be  a-type  value  designating  the  type  of  the  vector.  If 
s_C-type-vector-element-name  is  nil,  this  value  will  not  be 
included  as  the  first  element  of  the  vector  (it  can  still  be  found  by 
LISP  via  the  property  list  element  of  the  vector). 

If  s_C-type-vector-element-name  is  nil,  the  SOB^VFIRST  union 
and  all  if^define^s  using  it  will  be  omitted.  This  means  that  C 
code  will  not  be  able  the  access  the  type  or  vsize  of  the  vector  or 
any  part  of  the  hunk. 

S_C-plist-vec  tor-element-name  and  s_C-vsize-vector-element- 
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name  are  the  names  of  the  C  structure  elements  that  may  be 
used  to  access  the  object  property  list  and  object  vector  size  in 
bytes.  They  default  to  <s_C-prefix>plist  and  <s_C- 
prefix >vsize,  respectively.  If  s_C-plist- vector-element-name  is 
nil,  its  definition  will  be  omitted  (it  will  also  be  omitted  if  s_C- 
type-vector-element-name  is  nil).  Similarly  for  s_C-vsize-vector- 
element-name. 

If  s_pointer-C-type  is  non-niV,  it  is  taken  as  the  name  of  a-typc 
which  can  be  used  as  an  s_attribute-type  for  elements  which  are 
pointers  to  objects  of  type  s_type.  The  default  value  of 
s_pointer-C-type  is  s_type.  S_pointer-C-type  may  be  used  in  the 
current  declaration:  i.e.  the  type  may  be  defined  in  terms  of 
itself.  The  associated  C  data  type  is  s_Gtype,  which  must  be 
non- nil,  or  s_pointer-C-type  will  be  ignored. 

If  s_allocate-C-type  is  non-nil,  it  is  taken  as  the  name  of  Q'type 
which  can  be  used  as  an  s_attribute-type  for  vector  elements 
which  are  direct  inclusions  of  objects  of  type  s_type.  The 
<s_C-prefix>alloc  macro  is  used  in  C  for  such  inclusions.  The 
default  value  of  s„allocate-C-type  is  nil.  It  will  be  ignored  if 
s_C-prefix  is  nil.  S^allocate-C-type  cannot  be  used  in  the  current 
declaration. 

<C-attribute-type-l >  is  an  appropriate  C  data  type,  such  as 
long,  short,  uchar,  or  satjlvalue.  S_C-attribute-name-2  is 
assumed  here  to  be  an  attribute  included  in  the  hunk  only,  at 
position  <x2>  in  the  hunk. 

Because  the  exact  form  of  storage  of  a  vector  is  subject  to 
change,  the  definitions  of  SOB^VPLIST,  S0B_VF1RST, 
SOB^VTYPE,  SOB_VSIZE,  and  <s_C-prefix> vsize  may  be 
withdrawn.  The  other  definitions  may  change  though  their  usage 
should  not. 

If  an  attribute  is  present  in  both  the  vector  and  the  hunk,  only  a 
way  of  accessing  the  vector  attribute  is  provided. 

With  these  definitions  one  can  use  statements  such  as— 


<s_C-type>  y  =  ...; 

One  should  not  set  attributes  from  C  code  if  they  occur  in  both 
the  vector  and  the  hunk. 

< S_c- prefix >  alloc  should  not  be  used  if  any  reference  to  the 
hunk  part  of  the  resulting  object  is  required,  as  it  does  not 
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allocate  the  hunk. 

HAS-VECTOR-TYPE:  Ty_allocate-C-type  and  ty_pointer-C-type,  if  given,  are  assigned  the 
has-vcctor-typc  attribute  value  ty_type.  If  ty_type  is  the  same  as 
ty_pointer-C-type,  it  is  given  itself  as  its  has-vcctor-typc  attribute. 

NOTE:  Dcclarc-vector-typc  expands  into  a  call  to  define- vector- type  nested  inside  an 
eval-when  [compile  eval  load). 

NOTE:  Attribute  and  operation  descriptors  can  be  made  for  a  vector  type  after  the  call 
to  declare- vector -type  or  define-vector-type  that  makes  the  type.  If  a  new 
descriptor  is  for  an  attribute  or  operation  declared  by  the  execution  of  declare- 
vector-type  or  define-vector-type,  the  descriptors  declared  by  that  execution  will 
become  ancestors  of  the  new  descriptor. 

IMPLEMENTATION:  The  current  implementation  (which  is  subject  to  change)  represents 
the  object  by  an  immediate  vector  whose  property  (see  vprop)  is  a 
hunk.  The  first  element  of  the  hunk  is  set  to  the  object  type,  and 
the  restl  element  is  set  to  the  property  list  for  the  object.  The  rest 
of  the  hunk  elements  are  the  attributes  assigned  to  the  hunk  in  the 
order  of  their  appearance  in  the  call  to  declare-vector-type  or  define- 
vector-type. 

The  first  4  bytes  of  the  immediate  vector  optionally  hold  a  pointer  to 
the  object  type  (a  copy  of  the  first  element  of  the  hunk).  The 
remaining  bytes  hold  the  attributes  assigned  to  the  vector,  in  the 
order  of  their  appearance  in  the  call  to  declare-vector-type  or  define- 
vector-type.  Each  attribute  is  aligned  by  inserting  zero  padding  so 
that  its  displacement  within  the  vector  is  an  exact  multiple  of  its 
length.  1-bit  attributes  are  assigned  from  the  high  order  bits  to  the 
low  order  bits  within  one  byte. 

Attributes  made  for  a  vector  type  after  the  execution  of  declare- 
vector-type  or  define-vector-type  will  not  be  assigned  to  elements  of 
the  vector  or  hunk,  but  will  be  put  on  the  property  list. 

(define- attribute  ’s_name)  [LISP  Function] 

USE  ONLY  WHEN:  Using  define- object-name-prefix. 

EQUIVALENT  TO:  [an-attribute  has-name  s_name) 
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(define-object-name-prefix  ’s_prefix  ^s^function)  [LISP  Function] 

USE  ONLY  WHEN:  Adding  a  new  attribute  name  prefix  for  attribute  names  that  will  be 
used  in  data  ba^es. 

SIDE  EFFECT:  Specifies  that  whenever  the  value  of  an  unbound  symbol  beginning  with 
s^prefix  is  gotten,  s_function  will  be  called  with  the  symbol  as  its  only 
argument  in  order  to  bind  the  symbol.  Similarly,  if  the  symbol  has  a  nil 
function  definition  and  is  called  or  sjunction  is  called  (the  cmacro 
property  of  the  function  should  also  be  nil,  or  it  may  be  used  as  the  func¬ 
tion  definition). 

If  ajunction  is  nil,  no  function  will  be  called  for  the  prefix. 

NOTE:  The  default  object  name  prefixes  include— 


NOTE: 


a-  define-type 

an-  define-type 

has-  define-attribute 

do-  define-attribute 

dont-  define-attribute 

is-  define-attribute 

isnt-  define-attribute 

As  a  general  rule,  any  auxiliary  verb  (has,  have,  do,  is,  should,  ...)  or  preposition 
(to,  by,  ...)  followed  by  a  hyphen  may  be  declared  a  prefix  for  attribute  names. 

In  order  to  make  s_prefix  indicate  that  a  symbol  is  a-type  name  (like  a-  and  an-), 
sjunction  should  be  define-type.  In  order  to  make  s_prefix  indicate  that  a  sym¬ 
bol  is  an-attribute  name  (like  has-),  s_function  should  be  define-attribute. 


(define-type  ’s_name)  [LISP  Function] 

USE  ONLY  WHEN:  Using  define-object-name-prefix. 

EQUIVALENT  TO;  {a-type  has-name  s_name). 


(equal-property-lists  M_list-1  MJist-2)  [LISP  Function] 

WHERE:  Both  Llist-1  and  Llist-2  are  assumed  to  have  an  even  number  of  elements  and 
be  organized  as  attribute  label/value  pairs,  where  no  attribute  label  appears 
twice.  It  is  assumed  that  no  attribute  value  is  nil  in  either  list. 

RETURNS:  Non-nil  if  the  attributes  of  Llist-1  and  Llist-2  are  equal.  Note  that  the  attri¬ 
bute  labels  are  compared  using  eq  instead  of  equal. 
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(equal-property-lists-with-switches  ’Llist-1  M_list-2  LISP  Function] 

’Linfo) 

USE  ONLY  WHEN:  Building  new  object  subpackages:  like  those  of  declare-linttk-type  or 
declare- vcctor-typc. 

WHERE:  LJist-1  and  Llist-2  are  property  lists  each  with  an  even  number  of  elements 
and  no  attribute  whose  value  is  nil.  L_info  is  the  value  returned  by— 

{get-switch-info  ty^type  ...  ^^get-conipare-^untcli) 
and  is  used  to  quickly  find  the  value  of— 

{get-compare-switch  at_attribute  ty_type) 
for  any  at_attribute  that  can  be  in  either  Llist-1  or  Uist-2. 

W.*\RN1NG:  The  types  of  the  arguments  are  not  checked. 

RETURNS:  M/ if  IJist-l  and  Llist-2  have  an  unequal  attribute,  and  /  otherwise.  Ecjual- 
ity  of  the  two  values  of  the  attribute  labeled  at_attribute-l  is  tested  accord¬ 
ing  to  the  value  of— 

{get-compare-switch  at^attribute  ty^type) 

as  computed  using  the  third  argument  to  eqnal-properfy-lisis-irilh-.^tritrhes. 
If  this  switch  is  yes  or  n:7,  the  two  values  are  tested  with  equal.  If  it  is  no,  the 
two  values  are  presumed  equal  no  matter  what  their  actual  values  are:  i.e.  the 
test  for  equality  is  skipped  over.  If  it  is  any  other  value,  its  is  called  in  place 
of  the  equal  function  to  test  the  two  values  for  equality. 

SIDE  EFFECT:  If  an  attribute  is  not  found  in  the  third  element  of  Linfo.  it  is  found  by 
calling  get-switch-frovx-info  which  adds  the  attribute  to  the  third  element 
of  Linfo. 


(execute-operation  ’op_operation  *ob_object  ...) 

(execute- found-operation  ’opd_descriptor  ’op_operation  ...) 
(execute-parent-operation  ’opd_descriptor  ’op_operation 

’ob^object  ...) 

(lexpr-execute- found-operation  ’opd_descriptor  ’op_operation  ...) 
(lexpr-execute-parent-operation  ’opd_descriptor  ^op_operation 

’ob^object  ...) 

USE  ONLY  WHEN:  Execute-found-operation,  execute-parent-operation, 
found- operation,  and  lexpr-execute-parent-operation 
when  defining  non-standard  SKETCH  operations. 


^LISP  Macro] 
[LISP  Macro] 
[LISP  Macro] 

[LISP  Macro] 
[LISP  Macro] 


lexpr-execute- 
are  used  only 


WHERE:  The  last  argument  to  lexpr-execute-found-operation  or  lexpr-execute-parent- 
operation  is  treated  as  the  last  argument  to  lexpr-fnncali  namely,  as  a  list  of 
the  remaining  arguments  necessary  to  make  a  call  to  execute- found- operation  or 
execute-parent- operation. 


Op_operation  and  opd_descriptor  may  be  pre-evaluated. 

RETURNS:  The  value  of  the  operation  op_operation  applied  to  the  the  arguments  with 
opd^descriptor  and  op_operation  omitted.  Except  for  {lexpr-)execute-found- 
operation,  the  argument  ob^object  is  necessary  to  provide  a  type  used  in 
finding  the  operation  descriptor  needed  to  execute  the  operation. 
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EFFICIENCY:  These  macros  may  find  the  operation  descriptor  required  to  execute  the 
operation  at  macro  expansion  time,  and  produce  much  more  efficient  com¬ 
piled  code,  if  op_operation  is  the  name,  s_operation,  of  an^operation,  if 
ob_object  is  an  expression  of  the  form 

(s.type  ...) 

where  s_type  is  the  name  of  a-type^  and  if  opd_descriptor  is  pre-evaluated 
or  is  the  name,  s_descriptor,  of  an  operation  descriptor. 


If  the  descriptor  can  be  determined  at  macro  expansion  time,  and  a  has- 
macro  attribute  is  available  from  the  descriptor,  then  that  macro  can  be 
invoked  to  get  even  further  efficiency.  However,  this  macro  cannot  be 
invoked  by  the  Icxpr  forms  of  the  above  macros. 

DESCRIPTOR  SEARCH:  Execute- found- operation  performs  the  operation  using  the  given 

opd_descriptor,  which  was  presumably  found  by  calling  find- 
operation- descriptor. 


Execute- operation  searches  for  an  appropriate  descriptor  by  cal¬ 
ling- 

{find-operation-descriptor  nil  op.operation  {has-type  ob_object)). 

Execute-parent-operation  searches  for  an  appropriate  descriptor, 
starting  with  the  parent  of  opd_descriptor,  by  calling— 

[find-operation-descriptor  opd^descriptor  op_operation 

[has-type  ob_object)). 


equivalent  TO: 


is  equivalent  to— 


[execute-operatioTi  ...) 


[execute-parerit-operation  nil ...). 


(find-get-attribute-descriptor  ’atd_descriptor  ^at_attribute  [LISP  Function] 

’ty.type) 

(find-set-attribute-descriptor  ’atd_descriptor  ’at_attribute  [LISP  Function] 

’ty.type) 

(find-get-attribute-descriptor-for-macro  ’g_descriptor  ’g_attribute  [LISP  Function] 

’g_type) 

(find-set-attribute-descriptor-for-macro  ’g_descriptor  ’g_attribute  [LISP  Function] 

’g_type) 

WHERE:  For  the  for-macro  functions  the  arguments  are  macro  expansion  time  expres¬ 
sions  which  will  evaluate  at  eval  time  into  arguments  for  the  non-for-macro 
versions  of  these  functions. 


RETURNS:  An- attribute- descriptor  with  a  non-ni7  has- get- Junction  (for  find-get-attribute- 
descriptor)  or  has- set- function  (for  find-set-attribute-descriptor)  in  its  has- 
functions  table.'  This  descriptor  is  found  by  searching  using  at_attribute  and 
ty_type,  starting  the  search  with  the  parent  of  atd_descriptor.  If 
atd_descriptor  is  ni/,  all  applicable  descriptors  are  searched.  Nil  is  returned  ’f 
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the  descriptor  cannot  be  found. 


It  is  permissible  for  the  at_attribute  or  ty_type  arguments  to  be  7»7,  indicat¬ 
ing  an  absence  of  information.  In  this  case  it  may  not  be  possible  to  complete 
the  search,  and  nil  will  be  returned  to  indicate  this  fact. 


The  for-macro  versions  of  these  functions  assume  that  they  are  running  at 
macro  expansion  time  and  have  been  passed  the  expressions  which  are  to  be 
evaluated  at  eval  time  in  a  call  to  the  associated  non-for-macro  function.  The 
Jor-macro  functions  attempt  to  deduce  at  macro  expansion  time  what  the 
result  will  be  at  eval  time,  and  return  that  result  if  they  can  make  the  deduc¬ 
tion.  They  return  nil  if  they  cannot  make  the  deduction.  They  apply  object- 
expression-is  to  their  type,  attribute,  and  attribute  descriptor  arguments,  and 
thus  understand  arguments  which  are  names  of  descriptors,  attributes,  or 
types,  arguments  which  are  pre-evaluated,  and  arguments  of  the  form— 

[has- typ €  {s^type  ...)). 

NOTE:  If  ty^type  is  a  a-type  stub,  the  call— 

[dcfinc-type-stub  ty_type) 

is  made  to  fill  it  in. 


(find-operation-descriptor  ’opd_descriptor  *op_operation  ’ty_type) 
(find-operation-descriptor-for-macro  ’opd.descriptor 

’op_operation  'ty.type) 

RETURNS:  Aji-operalion-descriptor  found  by  searching  using  op_operation  and  ty_type, 
starting  the  search  with  the  parent  of  opd_descriptor.  If  opd^descriptor  is 
nily  all  applicable  descriptors  are  searched.  Nil  is  returned  if  the  descriptor 
cannot  be  found. 


[LISP  Macro) 
[LISP  Function) 


Ty— type  or  op^operation  may  be  nil  to  indicate  lack  of  information.  In  this 
case  it  may  not  be  possible  to  find  the  descriptor,  and  nil  will  be  returned, 
even  though  a  descriptor  could  be  found  if  both  ty_type  and  op_operation 
were  known. 


The  for-macro  version  of  this  function  assumes  that  it  is  running  at  macro 
expansion  time  and  has  been  passed  the  expressions  which  are  to  be  evaluated 
at  eval  time  in  a  call  to  the  associated  non-Jor-macro  function.  The  for- 
macro  function  attempts  to  deduce  at  macro  expansion  time  what  the  result 
will  be  at  eval  time,  and  return  that  result  if  it  can  make  the  deduction.  It 
returns  nil  if  it  cannot  make  the  deduction.  It  applies  object- expression- is  to 
its  type,  operation,  and  operation  descriptor  arguments,  and  thus  under¬ 
stands  arguments  which  are  names  of  descriptors,  operations,  or  types,  argu¬ 
ments  which  are  pre-evaluated,  and  arguments  of  the  form— 


[lias-type  (s_type  ...)). 
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(format-object  'ob_object  ’xjevel)  [LISP  Macro] 

WHERE:  Where  xjevel  (0,  1,  2,  ...)  is  the  depth  of  parentheses  or  brackets  within  which 
ob_object  is  being  printed. 

RETURNS:  A  LISP  value  which  when  pretty-print-JormaCed  will  print  a  representation  of 
ob_object  on  an  appropriate  nuniber  of  lines  with  appropriate  indentation. 
The  format  of  the  returned  value  is  discussed  under  pretty-print-format. 

All  SKETCH  objects  indexed  by  their  has-name  attribute  will  be  represented 
by  their  index,  the  symbol  which  is  the  value  of  that  attribute.  If  xjevel  is  0, 
an  exception  will  be  made,  and  ob_object  will  be  represented  as  a  type  and 
attribute  list  in  the  usual  way. 


Other  kinds  of  indexing  may  or  may  not  behave  similarly. 

EFFICIENCY:  This  macro  compiles  more  efficient  code  if  ob_object  is  an  expression  of  the 
form  — 

(s_type  ...) 

whose  type  s_type  is  specified  at  compile  time. 

H.\S-FORiVL\T-SWITCH:  If  an  attribute,  at_attribute,  of  an  object  of  type  ty_type  has  a 

non-nil  value  of— 

{get-format-switch  ty_type  at^attribute), 

then  in  any  call  to  format-object,  this  value  will  control  inclusion 
of  the  attribute  in  the  format  returned.  If  the  switch  is  no,  the 
attribute  will  not  be  included.  If  the  switch  is  yes  or  nil,  the 
attribute  will  be  included,  and  its  value  will  be  formatted  by  cal¬ 
ling  pretty-format.  If  the  switch  is  another  symbol,  that  symbol 
will  be  taken  as  the  name  of  a  function  to  be  called  in  place  of 
pretty-format  to  format  the  attribute  value.  The  value  returned 
by  this  function  will  be  used  as  the  format  of  the  attribute  value 
inside  the  object  format,  unless  this  returned  value  is  nil,  in  which 
case  the  attribute  will  not  be  included  in  the  object  format.  See 
HAS-FORMAT-SWITCH  under  an-attribute-descriptor. 


(get- attribute  *at_attribute  ’ob^object  ...) 
(get-found-attribute  'atd_descriptor  'at_attribute 

’ob_object  ...) 

(get-parent- attribute  ’atd_descriptor  ’at_attribute 

^ob_object  ...) 

(lexpr-get-found-attribute  ’atd^descriptor  ’at_attribute 

’ob_object  ...) 

(lexpr-get-parent- attribute  ’atd^descriptor  ^at_attribute 

’ob_object  ...) 


[LISP  Macro] 
(LISP  Macro) 

[LISP  Macro] 

(LISP  Macro] 

[LISP  Macro) 


USE  ONLY  WHEN:  Get-found-attribnte,  get-parent-attribute,  lexpr-get-foinul-attribute,  and 
lexpr-get-parent-attribute  are  only  used  when  defining  non-standard 
SKETCH  attributes. 
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WHERE;  The  last  argument  to  lexpr-gct-found-attribute  and  lexpr-get-parent-attribute  is 
treated  as  the  last  argument  to  lexpr-funcall,  namely  as  a  list  of  the  remaining 
arguments  necessary  to  make  a  call  to  get- found- attribute  or  get-parent- 
attribute. 

At_attribute  and  atd_descriptor  may  be  pre-evaluated. 

RETURNS:  The  value  of  the  attribute  labeled  at_attribute  for  ob_object.  If  the  attribute 
has  never  been  assigned  a  value  for  the  object,  nil  is  returned.  See  DESCRIP¬ 
TOR  SEARCH  below  to  determine  which  attribute  descriptor  is  used  to  get 
the  attribute  value. 

WHEN  SETF:  The  value  of  the  attribute  is  changed.  See  DESCRIPTOR  SEARCH  below 
to  determine  which  attribute  descriptor  is  used  to  set  the  attribute  value. 

EFFICIENCY:  These  macros  may  find  the  attribute  descriptor  they  need  to  get  or  set  the 
attribute  value  at  macro  expansion  time,  and  be  much  more  efficient  when 
compiled,  if  at_attribute  is  the  name  s_attribute  of  an-attribute,  ob_object 
is  an  expression  of  the  form-" 

(s_type  ...) 

where  s_type  is  the  name  of  a  type,  and  atd_descriptor  is  the  name, 
s_descriptor,  of  a  descriptor,  or  is  pre-evaluated. 

If  the  descriptor  can  be  determined  at  macro  expansion  time,  then  the 
has-get-macro  or  has-set-macro  macros  for  the  attribute  may  be  invoked  if 
they  are  defined,  to  get  even  further  efficiency  (see  an-attribute-function- 
table).  However  these  latter  macros  cannot  be  invoked  by  the  lexpr  forms 
of  the  above  macros. 

DESCRIPTOR  SEARCH:  Get- found- attribute  gets  the  attribute  using  the  given 

atd^descriptor.  This  descriptor  must  have  an  associated  has- get- 
function. 

Get- attribute  sedivches  for  an  appropriate  descriptor  by  calling— 
{find- get-attribute-descriptor  nil  at^attribute  {has-type  ob_object)). 

Get-parent-attribute  searches  for  an  appropriate  descriptor,  start¬ 
ing  with  the  parent  of  the  atd_descriptor  argument,  by  calling— 

{find-get-attribute- descriptor  atd_descriptor  at_attribute 

{has-type  ob^object)). 

^  If  an  attribute  is  being  set,  instead  of  gotten,  find-set-attribute- 

descriptor  is  used  instead  of  find-get-attribute-descriptor  to  find 
descriptors. 
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(get- attribute-descriptor  ’atd_descriptor)  [LISP  Function] 

USE  ONLY  WHEN:  Defining  non-standard  SKETCH  types  and  attributes. 

RETURNS:  An  expression  which  evaluates  to  atd_descriptor  in  the  eval  environment. 
This  is  non-trivial  when  get- attribuU- descriptor  is  called  at  compile  time. 


If  atd_descriptor  has  a  non-nil  lias-name  attribute,  that  attribute  is  returned 
as  the  value  of  get-attribute-descriptor  at  compile  time. 

WARNING:  The  assumption  is  made  that  all  the  descriptors  with  the  same  has- 
descriptor-type  and  has- descriptor- attribute  as  atd_descriptor  are  made  in  the 
same  order  in  both  the  compile  and  evaluation  environments. 

WARNING:  Although  get-attribute-descriptor  performs  the  same  function  as  a  macro,  it 
cannot  be  called  like  a  macro.  The  reason  it  is  not  a  macro  is  that  some 
dumb  macro  expanders  exist  which  will  recursively  expand  top  level  macros 
but  will  not  expand  arguments  to  functions,  and  would  end  up  trying  to  out¬ 
put  attribute  descriptors  as  literals  in  program  binaries. 


(get-default-value  ’at_attribute  ’ty^type  [’atd_descriptor)) 
(get-is-a-stub-switch  ’at_attribute  Yy_type  [*atd_descriptor]) 
(get-compare-switch  ’at_attribute  Yy_type  patd_descriptorj) 
(get-format-switch  ’at_attribute  ’ty_type  [’atd_descriptor)) 
(get-uneval-switch  'at_attribute  ’ty_type  [’atd_descriptor]) 


[LISP  Function] 
[LISP  F unctionj 
[LISP  Function] 
[LISP  Function] 
[LISP  F unction) 


USE  ONLY  WHEN:  Defining  non-standard  SKETCH  types  and  attributes. 

RETURNS:  The  first  non-nil  has- def ault- value ^  lias-is-a-stub-switch,  or  has-compare- 
switcli  lias-format-switch,  or  has-uneval-switch  obtained  by  searching  the 
attribute  descriptors  in  the  order  indicated  under  aii-attribute-descriptor. 
Returns  nz7  if  no  non- 7m7  value  found. 


If  the  atd_descriptor  argument  is  present  and  non-nil,  only  descriptors  after 
atd^descriptor  in  the  search  order  are  searched. 

(get-operation-descriptor  ’opd_descriptor)  [LISP  Function) 

USE  ONLY  WHEN:  Defining  non-standard  SKETCH  types  and  operations. 

RETURNS:  An  expression  which  evaluates  to  opd_descriptor  in  the  eval  environment. 
This  is  non-trivial  when  get-operation-descriptor  is  called  at  compile  time. 

If  opd_descriptor  has  a  non-nil  has-name  attribute  value,  that  value  is 
returned  as  the  value  of  get-operation-descriptor  at  compile  time. 

WARNING:  The  assumption  is  made  that  all  the  operation  descriptors  with  the  same 
has- descriptor- type  and  has- descrip  tor -operation  as  opd_descriptor  are  made 
in  the  same  order  in  both  the  compile  and  evaluation  environments. 

WARNING:  Although  get-operation-descriptor  performs  the  same  function  as  a  macro,  it 
cannot  be  called  like  a  macro.  The  reason  it  is  not  a  macro  is  that  some 
dumb  macro  expanders  exist  which  will  recursively  expand  top  level  macros 
but  will  not  expand  arguments  to  functions,  and  would  end  up  trying  to  out¬ 
put  attribute  descriptors  as  literals  in  program  binaries. 
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(get-switch-from-info  'at_attribute  M_info  s_switch)  [LISP  Macro] 

USE  ONLY  WHEN:  Building  new  object  subpackages:  like  those  of  declare’liunk-type  or 
dtclarc’Vtcior-  type. 

WHERE:  LJnfo  is  a  result  returned  by  gti-swiich-info  and  has  the  form  — 

(ty_type  (s_switch-l  ...)  ((at_attribute  s_switch-2)  ...)  s_default-switch) 
and  s_switch  is  one  of  the  symbols— 

has- is- a- stub- switch 
has- compare-switch 
has- format- switch 
has-uneval- switch 

Note  that  s_switch  is  an  unevaluated  argument. 

RETURNS:  The  switch  value  obtained  by  searching  the  third  element  of  Linfo,  the  list— 

((at_attribute  s_switch-2)  ...) 

for  a  match  to  at_attribute.  If  not  found,  the  switch  is  retrieved  by  invoking 
an  abbreviated  form  of  the  get-xxx-switch  function  (where  s_switch  equals 
has-xxx)  which  bypasses  the  search  for  group  1  attribute  descriptors  (those 
with  both  type  and  attribute  specified:  see  SEARCH  ORDER  under  (i7\- 
attribute-descriptor)  and  uses  the  fourth  element  of  Linfo  in  place  of  the 
search  for  group  3  descriptors  (those  with  the  given  type  but  any  attribute). 
The  switch  found  by  this  method,  even  if  nj7,  is  pushed  onto  the  third  element 
of  Linfo,  so  it  will  be  found  the  next  time  it  is  used. 

All  this  is  done  with  in-line  code  for  speed. 

(get-switch-info  ’ty_type  *(atd_descriptor  ...)  [LISP  Function] 

^u_get-switch-function) 

USE  ONLY  WHEN:  Building  new  object  subpackages:  like  those  of  declare-hunk-type  or 
declar  e-vector- type. 

WHERE:  U_get-switch-function  is  get-uneval- switch,  get-format-switch  or  some  simi¬ 
lar  function. 

WARNING:  The  types  of  the  arguments  are  not  checked. 

RETURNS:  A  list  (called  the  switch  info)  of  the  form— 

(ty^type  (s^witch-1  ...)  ((aLattribute  s_switch-*2)  ...)  s_default-switch) 

The  sublist  (s_switch-l  ...)  corresponds  to  the  list— 

(atd^descriptor  ...) 

with  s^switch  equal  to— 

[funcall  u_get-switch-function  [has- descriptor -attribxite  atd_descriptor)  ty_type). 


The  sublist— 


((aLattribute  s_switch-2)  ...) 
is  made  by  taking  for  each  descriptor  D  in  the  list— 
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{has- attribute- descriptors  ty^type), 
the  attribute  A  equal  to— 

(has- descnptor-ai tribute  D), 

and  the  pair  P  equal  to— 

‘(,A  j{funcall  u_get-svvitch-function  A  ty_type)), 

and  including  P  in  the  output  list  if  the  attribute  A  is  not  the  attribute  of 
any  element  of  the 

(atd_descriptor  ...) 


list. 


The  s_default-switch  is  the  value  of  the  switch  found  by  using  u_get-switch- 
function  to  search  for  a  switch  ignoring  group  1  and  2  attribute  descriptors 
(see  SEARCH  ORDER  under  an-attribute-descriptor). 

(has-lisp-type  g_value)  [LISP  Function) 

RETURNS:  The  SKETCH  type  corresponding  to  the  LISP  type  of  g_value,  according  to 
the  following  table— 


LISP  TYPE 

SKETCH  TYPE 

LISP  TYPE 

SKETCH  TYPE 

fixnmn 

a-Bxnum 

binary 

a-binary-function 

biqnum 

a-bignum 

value 

a-value 

flomnn 

a-flonum 

hunkO 

a-hunk 

string 

a-string 

liunkl 

a-hunk 

symbol 

a-symbol 

hunks 

a-hunk 

port 

a- port 

hunks 

a-hunk 

list 

a-list 

hunk  4 

a-hunk 

vector 

a-lisp-vector 

hunks 

a-hunk 

vectori 

an-immediate-vector 

hunks 

a-hunk 

array 

a-lisp-array 

NOTE;  The  type  returned  is  not  the  type  of  g_value  as  a  SKETCH  object,  but  rather  its 
type  as  a  LISP  object.  Thus— 

(has-lisp-type  an-attribute) 

would  be  something  like  a-hunkj  depending  on  implementation,  whereas— 

(lias-type  an-attribute) 

would  always  be  a-type. 
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(has-name  ’ob^object)  [SKETCH  Attribute] 

make-name-function  [LISP  Function  Name] 

make-name-macro  [LISP  Macro  Name] 

VALUE:  {has-name  ob_object)  is  the  name  of  ob^object.  This  is  a  symbol  whose  value  is 
always  equal  ob_object,  provided  the  symbol  is  not  nil. 

WHEN  SETF:  [has-name  ob^object)  cannot  be  self. 

INDEXING:  For  most  object  types,  an  object  made  by  the  call— 

(s_type  has-name  *s_name  ...) 

is  indexed  by  the  symbol  s_name's  being  set  equal  to  the  object. 

STUBS:  A  SKETCH  object  with  its  has-name  attribute  a  non-ni7  symbol,  but  no  other 
attribute  non- mV,  is  called  a  stub. 

If  a  stub  is  made  by  a  call  such  as— 

(s_type  has-name  ’s_name), 

and  an  object  with  the  same  has-7iame  already  exists,  the  stub  is  discarded,  and 
the  previously  existing  object  returned  as  the  result  of  making  the  object. 

If  an  object  which  is  not  a  stub  is  made,  and  a  stub  already  exists  with  the  same 
has-name,  then  the  attributes  of  the  existing  stub  are  set  to  those  of  the  newly 
created  object,  the  newly  created  object  is  discarded,  and  the  existing  object, 
now  no  longer  a  stub,  is  returned  as  the  result  of  the  call  making  the  object. 

If  an  object  which  is  not  a  stub  is  made,  and  another  object  not  a  stub  already 
exists  with  the  same  has-name,  then  the  two  objects  are  tested  for  equality  by 
compare-object,  and,  if  equal,  the  new  object  is  discarded,  and  the  existing  object 
returned  as  the  result  of  the  call  making  the  object.  It  is  an  error  if  the  objects 
are  not  equal. 

This  behavior  may  be  modified  for  some  types  of  objects,  in  which  case  the 
modified  behavior  is  documented. 

COMPILE  TIME  DECLARATIONS:  Making  an  object  with  a  non-nil  symbol  has-najne  attri¬ 
bute  at  compile  time  causes  the  symbol  to  be  declared  to 
be  special. 

NON-SYMBOL  VALUES:  Has-name  attribute  values  must  normally  be  symbols. 

IMPLEMENTATION:  Has-name  indexing  is  implemented  by  make-name-function  and 
make-name-macro  which  are  used  as  the  make-object  an-operation- 
descriptor  has-function  and  has-macro  values  for  basic  data  types 
(e.g.  those  defined  by  declare-hunk-type). 

The  default  has-is-a-stub-switch  value  for  has-name  is  no,  while  the 
default  has-set-function  makes  setting  a  has-7iame  attribute  illegal, 
and  the  default  has-init-function  makes  it  illegal  to  initialize  a  has- 
name  attribute  to  a  non-symbol  value. 
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(has-size  ’ty.type)  jSKETCH  Attribute) 

VALUE:  The  length  in  bits  of  a  datum  of  type  ty^type  from  the  point  of  view  of  the  C 
language.  E.g.,  [has-size  a-value)  is  32.  Used  in  allocating  arrays  of  objects  of 
the  given  type. 

(has-type  ’ob_object)  .  [LISP  Function) 

(has-type  *g_object)  [LISP  Function] 

has-typc  [SKETCH  Attribute] 

USE:  The  has-typc  attribute  value  of  a  SKETCH  object,  ob_object,  is  the  type  of 
ob^object,  and  specifies  the  format  of  the  object. 

The  has-typc  function  applied  to  any  LISP  object,  g-object,  which  is  not  a 
SKETCH  object,  will  return  the  value  returned  by  lias-lisp-type. 

INITI.ALIZATION:  It  is  illegal  to  initialize  the  lias-type  attribute  in  the  way  that  other 
attributes  are  initialized. 

WHEN  SETF:  It  is  illegal  to  setf  the  has-typc  attribute. 


(is-typed-expression  ’g_expression)  ‘LISP  .Macro) 

USE  ONLY  WHEN:  Defining  non-standard  SKETCH  types 
RETURNS:  The  type  named  by  s_type  if  g_expression  has  the  form-* 

(s_type  ...) 

where  s_type  is  the  name  of  a-typc.  Otherwise  returns  ml. 


*^make” 

“create’’ 

“index” 


[SKETCH  Term) 
[SKETCH  Term) 
[SKETCH  Term) 


USE:  Creating  an  object  and  indexing  an  object  are  part  of  making  an  object. 


To  make  an  object  is  to— 


(1)  Apply  initial  value  functions  or  macros  to  all  attribute 
values  provided  by  the  user. 

(2)  Find  default  values  for  all  attributes  for  which  values  were 
not  provided  by  the  user,  but  for  which  non-nil  default 
values  were  provided  for  the  type  of  the  object  being  creat¬ 
ed  (or  one  of  the  ancestors  of  this  type). 

(3)  Create  the  object. 
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(4)  Index  the  object.  Thai  is,  place  the  object  in  cross  refer¬ 
ence  lists;  and  do  processing  related  to  stubs  (see  has- 
name). 

(make-object  ’(ty_type  at^attribute  g_value  ...)  [SKETCH  Operation  Macro] 

(’ob^prototypej) 

(make-parent-object  ’opd_descriptor  [LISP  Macro] 

’(ty^type  at_attribute  g_value  ...)  [’ob^prototype]) 
make-object  [SKETCH  Operation] 

USE  ONLY  WHEN:  Make-parent-object  is  used  only  when  defining  non-standard  SKETCH 
types. 

WHERE:  Here  ...  is  a  list  of  attribute  label/value  pairs,  like  ‘at_attribute  g_value\  The 
entire  first  argument  is  called  an  ‘abnormal  object’  because  it  represents  an 
object  as  a  list,  the  first  of  whose  elements  is  the  type  of  the  object,  and  the  rest 
of  whose  elements  are  attribute  label/value  pairs. 

Ob_prototype  defaults  to  nil. 

Ob_prototype,  if  non- mV,  must  have  type  ty_type. 

Opd_descriptor  may  be  pre-evaluated. 

RETURNS:  An  object  of  type  ty_type  with  attribute  at_attribute  set  to  g_value,  and 
other  attributes  specified  similarly  by  the  ....  If  ob_prototype  is  non-niV,  it 
provides  default  values  for  all  unspecified  attributes.  Otherwise,  default 
values  are  provided  by  attribute  default  values  (see  HAS-DEF AULT- VALUE 
under  an-attribute-de$criptor).  Attribute  init  functions  or  macros  (see  HAS- 
INIT-FUNCTION  and  HAS-INIT-MACRO  under  an- attribute- function- table) 
are  applied  to  explicitly  given  attribute  values  (not  those  that  are  default 
values).  The  object  returned  is  both  created  and  indexed  (see  “r/iaArc”  and 
“s/u6s”). 

DEFAULT  MAKE:  The  default  behavior  of  make  is  usually  provided  by  the  make-name- 
function  and  make-name-macro,  which  consider  objects  with  not  attri¬ 
bute  but  a  has-name  to  be  stubs.  See  this  function  and  macro  in  the 
glossary. 

EFFICIENCY:  For  make-object  to  produce  efficient  code  during  compilation,  the  first 
argument  should  have  the  form  — 

(list  s_type  s_attribute  g_value  ...) 

where  ty_type  is  represented  by  its  name  s_type,  and  each  attribute  label 
is  represented  by  its  name  s_attribute.  Furthermore,  ob_prototype  must 
either  be  the  ni7  expression,  or  an  expression  of  the  form  — 

(s_type  ...) 

(which  promises  that  ob_prototype  is  a  non-r7»7  object  of  type  named  by 
s_type).  Then  much  of  the  work  of  make-object  is  done  at  macro  expan¬ 
sion  (i.e.  compile)  time. 
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Otherwise  all  the  work  will  be  done  at  eval  time. 

PROCESSING  ATTRIBUTES:  At  some  point  during  the  make  operation,  create-object  is 

called  to  create  the  object  (if  it  is  not  a  stub).  Just  before 
this  is  done,  the  abnormal  object  is  processed  by  either 
process-attributes  or  process- attributes- for-v\acro.  These 
functions  handle  default  values  and  has- init- function's  for 
attributes.  The  default  make  function  and  macro,  inake- 
name- function  and  make-name-macrOf  call  these  functions 
and  create-object. 

EQUIVALENT  TO:  Make-parent-object  is  equivalent  to— 

(execute-found-operation  (find-operation  make-object 

opd_descriptor 

ty_type) 

make- object 

(list  ty_type  at^attribute  g_value  ...)  ob_prototype) 

where  the  find-operation  is  performed  at  macro  expansion  time  if  pos¬ 
sible,  and  steps  are  taken  to  avoid  evaluating  ty^type  twice. 

Make-object  is  equivalent  to  make-parent-object  with  a  ml 
opd^descriptor. 

(merge-property-lists  ’Uist-1  ’Llist-2)  [LISP  Function] 

WHERE:  Both  Llist-l  and  Llist-2  are  assumed  to  have  an  even  number  of  elements  and 
be  organized  as  attribute  label/value  pairs,  where  no  attribute  label  appears 
twice. 

RETURNS:  LJist-1  with  any  properties  on  Uist-2  which  are  not  on  Llist-l  appended  to 
Llist-l.  Properties  with  a  nil  value  are  removed  from  Llist-l,  but  do  serve  to 
suppress  appending  of  Llist-2  properties  of  the  same  name.  LJist-1  is  des¬ 
troyed. 

(move-object  ’ob_object-l  ’ob_object-2)  [SKETCH  Operation  Macro] 

move-object  [SKETCH  Operation] 

RETURNS:  Ob_object-2  after  modifying  it. 

SIDE  EFFECT:  Moves  ob_object-l  into  ob_object-2.  This  means  ob_object-2  will  get 
exactly  the  same  attribute  values  as  ob_object-l. 

WARNING:  It  is  assumed  that  ob_object-l  will  be  discarded  immediately  after  the  move. 

Thus  any  property  lists  that  are  part  of  ob_object-l  may  be  moved  to 
ob_object-2  without  creating  new  list  elements,  for  example. 

EFFICIENCY:  This  macro  compiles  more  efficient  code  if  ob_object-l  is  an  expression  of 
the  form  — 

(s_type  ...) 

whose  type  s_type  is  specified  at  compile  time,  but  not  if  ob_object-2  is  of 
that  form. 
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(never-set-function  ’g_value  [LISP  Function] 

’atd.descriptor  ’at^attribute  ’ob^object  ...) 

(never-init-function  ’g_value  [LISP  Function] 

’atd_descriptor  ’at_attribute  'ty_type) 

USE  ONLY  WHEN:  Defining  non-standard  SKETCH  types  and  attributes. 

SIDE  EFFECT:  Calls  error  with  a  message  that  at_attribute  cannot  be  set/  or  init’ed  for 
an  object  of  type  {has-type  ob^object)  or  ty_type. 

USE:  Usable  as  the  has-set-function  or  has-init-function  value  for  an- attribute- function- 
table. 

(nu  11-property- list-with-switches  Uist  M_info)  [LISP  Function] 

USE  ONLY  WHEN:  Building  new  object  subpackages:  like  those  of  declare-hvnk-type  or 
declar  e-vector- type. 

WHERE:  L_list  is  a  property  list  with  an  even  number  of  elements  and  no  attribute 
whose  value  is  nil.  L_info  is  the  value  returned  by— 

{get-switch-info  ty_type  ...  ^'get-is-a-stub-switch) 
and  is  used  to  quickly  find  the  value  of— 

[get-is-a-stub-switch  at_attribute  ty_type) 
for  any  at_attribute  that  can  be  in  l_list. 

WARNING:  The  types  of  the  arguments  are  not  checked. 

RETURNS:  Nil  if  Llist  has  all  absent  attributes,  and  t  otherwise.  Whether  or  not  the 
value  of  the  attribute  labeled  at_attribute  is  absent  is  tested  according  to  the 
value  of— 

{get-is-a-stub-switch  at_attribute  ty_type) 

as  computed  using  the  third  argument  to  null-property-list-with-switches.  If 
this  switch  is  yes  or  nil,  the  value  is  tested  with  not,  and  thus  is  absent  only  if 
it  is  nil  (i.e.,  missing  from  the  property  list).  If  it  is  no,  the  value  is  presumed 
absent,  no  matter  what  it  is:  i.e.  the  test  is  skipped  over.  If  it  is  any  other 
value,  it  is  called  in  place  of  the  not  function  to  test  the  value  for  absence. 

SIDE  EFFECT:  If  an  attribute  is  not  found  in  the  third  element  of  Linfo,  it  is  found  by 
calling  get-switch-from-info  which  adds  the  attribute  to  the  third  element 
of  Linfo. 
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(object-expression-Ls  ’ty^type  ’g_expression)  [LISP  Macro] 

RETURNS:  The  object  that  g_expression  will  evaluate  to  at  eval  time,  if  this  can  be 
determined  at  compile  time,  and  if  this  object  is  of  type  ty_type.  Or,  if 
g_expression  is  an  object  of  type  ty_type,  returns  g_expression  (as  in  pre¬ 
evaluated  arguments  to  macros).  Otherwise  returns  nil. 

If  g_expression  is  a  symbol  which  is  the  has-name  of  an  object  of  type 
ty_type,  that  object  is  returned.  If  the  symbol  is  unbound,  it  will  first  be 
automatically  bound  by  the  dcfinc-objcct-namc-prefix  facility,  if  possible. 

As  a  special  case,  if  g_expression  has  the  form— 

{has-type  (s_type  ...)) 

and  ty_type  is  a-type^  then  g_expression  is  replaced  by  s_type. 

(object-is  ’ty_type  ’ob_object)  [SKETCH  Operation  Macro] 

(parent-object- is  ’opd_descriptor  ^ty_type  ’ob_object)  [LISP  Macro] 

USE  ONLY  WHEN:  Parent- object-is  should  be  used  only  when  defining  non-standard 
SKETCH  types. 

WHERE:  Opd_descriptor  may  be  pre-evaluated. 

RETURNS:  Non- nil  if  ob_object  has  the  type  ty_type.  Otherwise  nil. 

EFFICIENCY:  This  is  much  more  efficient  than  — 

{eg  ty_type  {has-type  ob_object)), 

when  ty_type  is  specified  by  its  name,  s_type,  at  compile  time,  or  when 
opd_descriptor  is  given  and  is  either  pre-evaluated  or  is  a  descriptor  name. 

EQUIVALENT  TO: 

{execute^ found- operation  object-is 

[find- operation- descriptor  opd_descriptor  object-is 

ty_type) 

ty_type  ob_object) 

where  opd^descriptor  is  nil  for  object-is,  the  call  to  find-operation  is 
performed  at  macro  expansion  time  if  possible,  and  steps  are  taken  to 
avoid  evaluating  ty_type  twice. 
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(object- is- a-stub  ’ob_object)  [SKETCH  Operation  Macro] 

object- is- a-stub  [SKETCH  Operation] 

RETURNS:  Non-n*/  if  ob_object  is  a  stub.  Otherwise  nil. 

The  standard  test  for  an  object  being  a  stub  is  to  test  each  attribute  as 
specified  by  the  attribute’s  its  has-is-a-stub-switch  value:  see  HAS-IS-A- 
STUB-SWITCH  under  an- attribute-descriptor.  If  this  switch  is  m7  or  yes,  the 
attribute  is  tested  by  the  not  function,  and  is  therefore  required  to  be  nil.  If 
this  switch  is  no^  the  attribute  is  not  tested  at  all.  If  this  switch  is  some 
other  symbol,  that  symbol  is  used  in  place  of  not  to  test  the  attribute  value. 
All  attributes  must  pass  their  tests  for  the  object  to  be  a  stub. 

Standardly  has-name  attributes  have  the  no  has-is-a-stub-switch  value,  and 
the  value  of  this  switch  for  all  other  attributes  is  not  specified  [nil). 

(object-symeval  ’s_j5ymbol)  [LISP  Macro] 

RETURNS:  The  value  of  the  symbol  if  it  has  one  or  can  be  bound  by  the  define- object- 
name-prefix  facility;  nil  if  the  symbol  is  unbound  and  cannot  be  bound  by 
that  facility. 

(s_operation  ’ob_object  ...)  [SKETCH  Operation  Macro] 

(s_operation  (s_type  ob_object  ...)  ...)  [SKETCH  Operation  Macro] 

WHERE:  S_operation  is  the  name  of  some  SKETCH  operation,  op_operation:  e.g.  make- 
object,  format-object. 

RETURNS:  The  value  of  executing  op^operation  on  the  arguments. 

EFFICIENCY:  The  form  with  (s_type  ob_object  ...)  rather  than  just  ob_object  is  often 
more  efficient  when  compiled,  because  s_type  tells  the  compiler  the  type  of 
ob_object. 

NOTE:  Some  operations  do  not  take  an  object  as  their  first  argument.  E.g.  make-object 
and  create-object  take  a  list  whose  first  element  is  the  type  used  to  control  the 
operation  behavior,  while  object-is  takes  that  type  directly  as  the  first  argument. 

EQUIVALENT  TO: 

{execute-operation  s^opeT2Ltioi\  ’ob_object  ...). 

However,  it  is  permissible  to  override  this  definition  by  setting  the 
function  definition  of  s^operation.  The  default  macro  definition  will 
not  replace  an  existing  definition. 
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(patom  (LISP  Function] 

equivalent  TO:  Normal  LISP  patom,  except  that  objects  which  have  a  has-name  attri¬ 
bute  are  represented  by  the  value  of  that  attribute. 


“p re-evaluated”  [SKETCH  Term] 

USE:  An  argument  to  a  macro  is  said  to  be  pre-evaluated  if  it  is  the  intended  argument 
value  itself,  as  opposed  to  an  expression  which  is  to  be  evaluated  at  some  later  time 
to  the  intended  value.  Thus  for  a  number  argument,  this  would  be  the  number 
itself,  which  can  also  serve  as  an  expression  that  evaluates  to  itself.  Other  pre¬ 
evaluated  arguments,  however,  are  not  expressions  that  evaluate  to  themselves, 
and  cannot  be  passed  to  code  that  expects  expressions  and  not  values. 

Attributes,  attribute  descriptors,  operations,  and  operation  descriptors  are  often 
passed  to  macros  as  pre-evaluated  arguments.  One  must  be  careful  not  to  output 
these  in  the  expansion  of  the  macro,  unless  that  expansion  also  calls  a  macro  that 
expects  pre-evaluated  arguments. 

(pretty-print  ’ob_object  ...)  [LISP  Function] 

EQUIV.-VLENT  TO:  For  SKETCH  Objects  (those  for  which  has-type  differs  from  lias-lisp- 
type)  pretty-print  uses  format-object.  .Also,  lists  in  the  format  of 
abnormal  objects,  either  using  symbols  to  name  the  type  and  attri¬ 
butes,  or  using  the  type  and  attribute  objects  themselves,  are  formated 
like  objects:  the  attribute  values  are  indented  with  respect  to  the  attri¬ 
bute  labels. 

(print  ...)  [LISP  Function] 

equivalent  TO:  Normal  LISP  print,  except  that  objects  which  have  a  lias-name  attri¬ 

bute  are  represented  by  the  value  of  that  attribute. 

(process- attributes  '(ty_type  at_attribute  g_value  ...)  [LISP  Function] 

’ob_prototype) 

(process-attributes-for-macro  '{list  s_type  s_attribute  g_value  ...)  [LISP  Function) 

’g-prototype) 

USE  ONLY  WHEN:  Defining  non-standard  SKETCH  make-object  operations. 

WHERE:  In  the  arguments  to  process-attributes-for-macro,  s_type,  s_attribute,  g_value, 
and  g^prototype  are  expressions  which  will  evaluate  at  eval  time  to  the 
corresponding  components  of  the  arguments  to  process-attributes. 

The  first  argument  to  process-attributes  is  an  abnormal  object:  see  make-object. 

RETURNS:  Process- attributes  returns  the  list— 

at_attribute  g^value  ...) 

with  default  values  appended  for  the  missing  attributes  that,  depending  upon 
ty_type,  should  have  default  values,  and  has- init- function's  called  for  expli¬ 
citly  given  attributes  that,  depending  upon  ty_type,  have  these  functions 
defined.  The  default  values  are  not  appended  if  ob_prototype  is  not  nil. 
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Process- attributes’ for-macro  is  similar  but  returns  the  list— 

{list  ty_type  at^attribute  g_value  ...) 
and  applies  lias-init- macro's  instead  of  calling  lias-init-function's. 

Process- attributes  obtains  default  values  by  evaf  ing  default  value  expressions 
associated  with  the  at_at tribute’s  and  ty_type.  It  applies  has- init- function's 
s_init-function  by  calling— 

(/uncfl// s_init-function  g_value  atd^descriptor  at_attribute  ty_type) 

for  each  explicitly  given  g_value  (not  for  default  values)  which  has  such  a 
function  associated  with  its  at_attribute  and  ty_type.  Here  atd_descriptor  is 
the  attribute  descriptor  that  contributed  s_init-function. 

Process- attributes- for-niacro  inserts  unevaluated  default  expressions  into  the 
returned  list.  It  replaces  each  unevaluated  explicitly  given  g^value  by  the 
result  of  applying  the  has-init-macro  s_init-macro  to  the  form— 

‘(,s_init-macro  ,g_value  ,atd_descriptor  ,at_attribute  ,ty_type) 
if  there  is  an  associated  has-init-macro^  or  by  the  form— 

‘(,s_init-function  ,g_value  {get-atlribute  .atd^descriptor) 

,{lias-itame  at_attribute)  ,(has-name  ty_type)) 

if  there  is  only  an  s_init-function.  Note  that  in  the  application  of  s_init- 
macro  the  arguments  at_attribute,  atd_descriptor,  and  ty_type  are 
preevaluated,  whereas  g_value  is  unevahiated. 

Calls  to  init  functions  or  macros  are  not  made  for  default  values  or  for  attri¬ 
butes  for  which  there  is  no  has-init-function  associated  with  at_attribute  and 
ty_type. 

In  the  case  of  process-attributes-for-macro^  s_type,  s_attribute,  and  g_value 
in  the  abnormal  object  list  are  yet  unevaluated,  and  it  is  not  possible  to  call 
init  functions  or  macros  or  to  append  default  values  unless  s_type  and  all  the 
attribute  labels  s^attribute  are  represented  by  their  names.  If  this  is  not  the 
case,  or  if  g_prototype  is  non-nil  and  does  not  have  the  form— 

(s_type  ...), 

process- attributes-for-macro  will  return  m7,  but  not  call  error. 

Lastly,  error  checking  is  done  on  the  list  and  prototype.  Process-attributes 
calls  error  if  it  discovers  that  the  first  element  of  the  list  is  not  a  type,  or  the 
even  numbered  elements  are  not  attributes,  or  the  list  length  is  not  odd.  It 
also  calls  error  if  the  prototype  is  not  nil  and  does  not  have  a  type  equal  to 
the  first  element  of  the  list.  Process-attributes-for-macro  simply  returns  nil  if 
there  is  any  problem  with  the  list. 

SIDE  EFFECT:  The  results  returned  are  copies  of  the  input  lists,  and  the  input  lists  are 
not  changed. 
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*read-write-password-attribute-fu actions*  (LISP  Global  Variable] 

*read-private-password-attribute-functions*  [LISP  Global  Variable] 

*private-password-attribute-functions*  [LISP  Global  Variable] 

USE  ONLY  WHEN:  Defining  non-standard  SKETCH  types  and  attributes. 

USE:  These  are  named  an^attributc-function’ tablets  which  may  be  used  to  define  an- 
attribute-descriptor  that  makes  an  attribute  handle  passwords.  The  password  must 
be  a  symbol  whose  value  equals  itself,  and  must  be  the  has-parameters  attribute  of 
the  attribute  descriptor  whose  has-functions  attribute  is  one  of  the  above  function 
tables. 

Thus  a  typical  use  is— 

{an- attribute- descriptor  has-descriptor-attribute  at^attribute 

has-descriptor-lype  ty_type 

has-functions  *read-private-password-atiribule-functions  ^ 
has-parameters  s^password) 

SIDE  EFFECT:  In  some  cases  a  password  argument  must  be  used  with  the  attribute 
When  required,  the  password  argument  must  be  the  first  extra  argument 
to  the  attribute,  as  in  any  of  the  following— 

(s^attribute  ob_object  s_password  ...) 

[get- attribute  at_attribute  ob_object  s_password  ..  ) 

[get-parent-attribiite  atd_descriptor  at^attribute  ob_object 
s_password  ...) 

The  password  must  be  used  to  read  the  attribute  if  the  function  table  is 
*private-password-attribute- Junctions*. 

The  password  must  be  used  to  write  the  attribute  if  the  function  table  is 
*  private-password- attribute- functions*  or  *  read-private-password- 

attribute-functions  *. 

In  other  cases  the  password  is  optional:  it  may  be  used  or  omitted. 

In  the  case  where  a  password  must  be  used  and  is  not,  error  will  be  called 
with  a  message  that  at^attribute  is  private  and  cannot  be  gotten  or  se//in 
objects  of  the  type  of  ob^object. 

In  all  cases,  if  the  attribute  read  or  write  is  allowed,  the  parent  get  or  set 
attribute  descriptor  will  be  used,  and  any  password  present  will  be 
removed  from  the  extra  argument  list  and  not  passed  to  the  parent. 
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(remove-abnormal-attributes  [do-return’rcally-iiU]  [LISP  Function] 

*(ty_type  at_attribute-l  g_value-l  ...) 

*at_attribute-l  1  ’at_attribute-r2  ...) 

(get- abnormal-attributes  [do-return-really-nil]  [LISP  Function] 

’(ty_type  at_attribute-l  g_value-l  ...) 

’at_attribute-ll  ^at_attribute-12  ...) 

USE  ONLY  WHEN:  Writing  create  and  make  functions  which  have  abnormal  object  argu¬ 
ments. 

RETURNS:  A  list  of  the  values  of  the  attributes  at_attribute-ll,  at_attribute-l2,  ... 
found  in  the  abnormal  object 

’(ty^type  at_attribute-l  g_value-l  ...) 

If  the  do-return-really-nil  switch  is  present,  the  value  returned  for  an  attri¬ 
bute  which  has  a  nil  value  in  the  abnormal  object  is  the  symbol  really-nil, 
whereas  the  value  returned  for  an  attribute  with  no  abnormal  value  is  nil. 
Without  the  do-re^tirn-rea//2/-m7  switch,  nil  'll  returned  in  both  cases. 

SIDE  EFFECT:  Remove- abnormal- attributes  removes  the  attributes  it  gets  from  the 
abnormal  object.  Get- abnormal- attribute'^  docs  not. 


[SKETCH  Term] 
[SKETCH  Argument  Prefi.x] 

A  SKETCH  object  is  one  whose  SKETCH  lias-type  value  is  a  type  delined  by 
declar e-hunk- type  or  declare-vector-type.  Note  that  types  that  appear  in  data  but 
have  not  been  declared  to  the  program  are  implicitly  declared  in  one  of  these  ways, 
and  are  SKETCH  object  types. 


“SKETCH  object” 
ob_ 

USE: 


LISP  numbers,  strings,  symbols,  lists,  and  ports  are  not  SKETCH  objects. 

ARGUMENT  PREFIX:  SKETCH  object  arguments  are  indicated  by  the  ob^  argument 
prefix.  This  is  less  general  than  the  prefix,  which  includes  both 
SKETCH  objects  and  other  LISP  objects  such  as  numbers  and  lists. 


sob_attribute 
at_ 

VALUE:  A  lisp  value  which  is  a  pointer  to  a  SKETCH  an-atlribute  object. 


[C  Type] 
[Argument  Prefix] 
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SOB_ATTRIBUTE 

[C  Global  Variable) 

SOBJBIGNUM 

[C  Global  Variable] 

SOB_BINARY 

[C  Global  Variable) 

SOB_CHAR 

[C  Global  Variable) 

SOBJDOUBLE 

jC  Global  Variable) 

SOB_FIXNUM 

[C  Global  Variable) 

SOB_FLOAT 

[C  Global  Variable) 

SOB_FLONUM 

[C  Global  Variable) 

SOB_HUNK 

[C  Global  Variable) 

SOBJNT 

[C  Global  Variable] 

SOBJVECTOR 

[C  Global  Variable) 

SOB_LARRAY 

[C  Global  Variable] 

SOB_LBIT 

[C  Global  Variable) 

SOB_LIST 

[C  Global  Variable] 

SOB_LONG 

]C  Global  Variable) 

SOB_LVECTOR 

[C  Global  Variable] 

SOB_NONLISP 

jC  Global  Variable) 

SOB_PORT 

[C  Global  Variable) 

SOB.SHORT 

[C  Global  Variable) 

SOB_STRING 

jC  Global  V^ariablej 

SOB_SYMBOL 

[C  Global  V'ariable] 

SOB_TYPE 

[C  Global  Variable) 

SOB_UBIT 

[C  Global  Variable) 

SOB_UCHAR 

[C  Global  Variable] 

SOB_ULONG 

]C  Global  Variable) 

SOB_UNSIGNED 

[C  Global  V'ariable] 

SOB_USHORT 

[C  Global  Variable) 

SOB_VALUE 

[C  Global  Variable] 

VALUE:  An  sat_lvalue  equal  to  a  SKETCH 

a-type  object,  according  to  the  following 

table— 


SOB_ATTRIBUTE 

SOBJBIGNUM 

SOB_BINARY 

SOB_CHAR 

SOBJDOUBLE 

SOB_FIXNUM 

SOB_FLOAT 

SOB_FLONUM 

SOB_HUNK 

SOB_INT 

SOB_IVECTOR 

SOBJLARRAY 

SOB_LBIT 

SOBJLIST _ 


an-attribute 

a-bignum 

a- binary- function 

a-char 

a-double 

a-fixnum 

a-Jioat 

a-flonum 

a-hunk 

an-int 

an-immediate-vector 
a-lisp-array 
an-lbit 
a- list 


SOBJLONG 

SOB_LVECTOR 

SOB_NONLISP 

SOB_PORT 

SOB_SHORT 

SOB.STRING 

SOB_SYMBOL 

SOB_TYPE 

SOB_UBIT 

SOB_UCHAR 

SOB_ULONG  . 

SOB_UNSIGNED 

SOB_USHORT 

SOB_VALUE 


a-long 

a-lisp- vector 

a-non-lisp- value 

a-port 

a-short 

a-string 

a-symbol 

a- type 

a-ubit 

a-ucliar 


a-ulong 
an- unsigned 
a-usliort 
a-value 
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sob_case  (ty_type)  [C  Functionl 

RETURNS:  An  integer  code  that  discriminates  between  different  nupieric  types  and  is 
suitable  for  use  in  a  case  statement.  The  codes  returned  have  names  such  as 
SOB^UBCASE  as  per  the  following  table— 


Ty type  Value 

Code  Returned 

Numeric  Type 

SOB.UBIT 

SOB.UBCASE 

unsiRned  1  bit  integer 

SOB CHAR 

SOB.CCASE 

siRned  8  bit  intcRer 

SOB.UCHAR 

SOB.UCCASE 

unsiRned  8  bit  intcRer 

SOB SHORT 

SOB SCASE 

signed  16  bit  integer 

SOB.USHORT 

SOB.USCASE 

unsigned  16  bit  integer 

SOB_LONG 

SOBJNT 

SOBJLCASE 

signed  32  bit  integer 

SOB.ULONG 

SOB UNSIGNED 

SOB.ULCASE 

unsigned  32  bit  integer 

SO  REFLOAT 

SOBJFCASE 

signed  32  bit  floating  point  number 

SOB_DOUBLE 

SOB_DCASE 

unsigned  64  bit  floating  point  number 

If  ty_type  is  not  listed  in  the  above  table,  0  is  returned. 

sobjtype  (g^value)  [C  Macro] 

RETURNS:  The  sob^typc  for  the  SKETCH  type  associated  with  the  LISP  type  of  g^value. 

Th  is  LISP  type  is  the  same  as  returned  by  has- lisp- type.  Thus  if  g_value 
were  an-attribute^  sob_ltype  would  return  something  like  SOB^HUNK.  see 
has-lisp-type\ 

sob_inissing  (x_type_case)  [C  Function] 

RETURNS:  The  missing  value  appropriate  to  the  data  type  ty_type  with— 

x_type_case  =sob_case  (ty_type). 

This  value  is  returned  as  a  double.  If  ty_type  has  no  missing  value,  some 
value  is  returned  which  is  never  taken  by  ty_type  values:  this  is  invariably 
SAT_DMISSING. 
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sob.nobject  {t_name)  [C  Function] 

RETURNS:  The  sat^lvaluc  which  is  the  object  whose  lias-name  attribute  value  is  the  sym- 
\x>\  sat^nsymbol  (tjame). 

BUG:  Behavior  is  undefined  if  there  is  no  such  object  but  there  is  a  bound  symbol  with 
the  name  t_name.  An  error  is  detected  only  if  the  symbol  t_name  is  unbound. 

sob.tsize  (ty_type)  [C  Function) 

RETURNS:  The  size  in  bits  of  a  datum  of  type  ty_type,  or  0  if  ty_type  is  not  a  valid  type 
or  has  no  specified  size.  This  size  in  bits  is  the  same  as  the  has-size  attribute 
of  ty_type  in  LISP. 


sob_type  [C  Type] 

ty_  [.Argument  Prefi.xj 

V.\LUE:  A  lisp  value  which  is  a  pointer  to  a  SKETCH  a-type  object. 


sob_vcreate  (ty_type) 


[C  F unction) 


RETURNS:  A  newly  created  object  of  type  ty_type.  The  object  is  the  same  as  would  be 
created  by— 

[create- object  [list  ty^type)  nil), 

except  that  element  default  values  which  are  not  constants,  but  which  require 
computation  to  produce,  are  ignored,  and  their  elements  take  the  values  they 
would  have  if  no  defaults  were  ever  given  for  them. 


Ty_type  must  have  been  defined  by  declare-vector-type  or  define-vector-type. 


Note  for  purposes  of  lint  that  the  value  returned  is  of  type  sat^lvalue. 


sob_vinit  (ob_object  ty_type)  (C  Function] 

RETURNS:  Ob_object  after  initializing  it. 


Note  that  for  purposes  of  lint  both  ob_object  and  the  value  returned  is  of 
type  satjvalue. 

SIDE  EFFECT:  Sets  all  of  the  vector  part  of  ob_object  just  as  they  would  have  been  set 
had  the  object  been  created  by— 

[create- object  [list  ty_type)  iiil). 

Ty_type  must  have  been  defined  by  declare-vector-type  or  define- vector- 
type.  The  hunk  part  of  the  object  is  not  touched,  and  in  fact  the  vector 
size  and  property  list  elements  of  the  vector  do  not  have  to  exist. 

USE:  To  initialize  vector  objects  created  in  the  stack.  E.g  — 


Printed  April  27,  1989 


OBJECTS 


5-82 


function  (...)  ...  { 

sag_talloc  (transform,  1); 

sob_vinit  (transform,  SAG_TRANSFORM); 

...} 

allocates  a  SAG_TRANSFORM  object  in  the  stack  and  initializes  it. 

“stub’»  (SKETCH  Term] 

USE:  A  stub  is  an  object  most  of  whose  attributes  are  yet  undefined,  but  which  has 
enough  defined  attributes  to  provide  some  kind  of  unique  referent  (e.g.  name)  for 
the  objcct.^tubs  are  considered  to  be  part  of  indexing,  and  are  handled  by  the 
operation.  The  general  rules  concerning  stubs  are  as  follows: 

(1)  If  a  stub  is  created  while  making  an  object,  and  an  object  with  the  same 
referent  already  exists,  the  stub  is  discarded,  and  the  pre-existing  object  is 
returned  as  the  result  of  making  the  object.  An  error  check  is  made  to  be 
sure  the  pre-existing  object  and  the  newly  created  stub  have  the  same 
type. 

(2)  If  a  non-stub  is  created  while  making  an  object,  and  a  stub  with  the  same 
referent  already  exists,  the  attributes  of  the  pre-existing  stub  are  filled  in 
with  the  attribute  values  from  the  newly  created  object  (by  movt^objcct), 
the  newly  created  object  is  discarded,  and  the  pre-existing  object  (the 
former  stub)  is  returned  as  the  result  of  making  the  object.  An  error 
check  is  made  to  be  sure  the  pre-existing  stub  and  the  newly  created  object 
have  the  same  type. 

(3)  If  a  non-stub  is  created  while  making  an  object,  and  a  non-stub  with  the 
same  referent  already  exists,  the  two  objects  with  the  same  referents  are 
checked  for  equality  by  comparc-objtct.  Inequality  is  an  error.  The  newly 
created  object  is  then  discarded,  and  the  pre-existing  object  is  returned  as 
the  result  of  making  the  object. 

(symbol-init-function  *g_value  [LISP  Function] 

’atd^descriptor  *at_attribute  *ty_type) 

(symbol-init-macro  *g_value  [LISP  Macro] 

atd_descriptor  at^attribute  ty_type) 

USE  ONLY  WHEN:  Defining  non-standard  SKETCH  types  and  attributes. 

SIDE  EFFECT:  Checks  that  g_value  is  a  symbol,  and  calls  error  if  not  with  a  message 
that  at_attribute  must  be  initialized  to  a  symbol  for  an  object  of  type 
ty_type. 

USE:  Usable  as  the  has-init-function  or  has- init- macro  value  for  an- attribute- function- 
table. 
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(symeval  ^s^symbol)  [LISP  Special  Function] 

WARNING:  When  compiled,  FRANZ  symeval  does  not  check  for  unbound  variables  and 
automatically  bind  them.  Use  object- symeval  instead  in  compiled  code  that 
is  to  automatically  bind  unbound  variables. 

*top-level-print*  [LISP  Global  Variable] 

SIDE  EFFECT:  This  variable,  which  is  defined  and  used  by  the  top  level  in  the  FRANZ 
EXTENSIONS  package,  is  set  by  the  OBJECTS  PACICAGE  to  print  only 
the  name  of  any  expression  value  with  a  non-m7  has-name  attribute, 
unless  that  name  is  eq  to  the  expression  that  was  evaluated  (as  stored  in 
the  global  variable  -f  by  the  top  level). 

(s_type  *at_attribute  ’g_value  ...)  [LISP  Macro] 

(s_type  *ob_object)  [LISP  Macro] 

(s_type  ’ob_object  ’at_attribute  *g_value  ...)  [LISP  Macro] 

WHERE:  S_type  is  the  name  of  a  SKETCH  type,  ty_type. 

RETURNS:  The  form  with  no  ob_object  returns  a  SKETCH  object  of  type  ty_type, 

at_attribute  value  g_value,  and  other  attribute  values  as  given  by 

Unspecified  attributes  will  be  given  default  values  determined  by  s_type  and 
at_attribute.  This  form  is  equivalent  to— 

[make-object  [list  s_type  at_attribute  g_value  ...)  nil) 

It  is  more  efficient  if  each  at_attribute  is  specified  by  its  name,  s_attribute. 

The  form  with  a  single  argument,  ob_object,  macro  expands  to  ob_object 
This  form  is  used  to  tell  other  macros  that  ob_object  is  necessarily  an  object 
of  type  ty_type.  For  example, 

[has-name  [an-attribute  x)) 
may  be  compilable  to  more  efficient  code  than— 

[has-name  x). 

However,  this  one  argument  form  does  not  usually  check  to  see  that  the  type 
of  ob_object  in  fact  is  ty_type,  so  the  programmer  must  avoid  mistakes. 

The  form  with  the  ob_object  argument  and  at_attribute/g_value  argument 
pairs  makes  a  new  object.  Attributes  not  specified  by  the 
at_attribute/g_value  pairs  are  taken  from  the  corresponding  attributes  of 
ob_object,  rather  than  being  given  default  values.  The  type  of  ob_object 
must  be  ty_type.  This  form  is  equivalent  to— 

[make-object  [list  s_type  at_attribute  g_value  ...)  (s_type  ob_object)) 

It  is  more  efficient  if  each  at_attribute  is  specified  by  its  name,  s^attribute, 
and  ob_object  is  an  expression  of  the  form  — 

(s_type  ...) 

which  promises  a  non-mV  value  of  the  correct  type. 

NOTE:  All  symbols  beginning  with  a-  or  on-  should  name  SKETCH  types,  and  all 
SKETCH  types  should  have  names  beginning  with  these  prefixes. 
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NOTE:  It  is  permissible  to  override  this  definition  by  setting  the  function  definition  of 
s_type.  The  default  macro  definition  of  s_type  will  not  replace  an  existing 
definition. 

(uneval-object  ’g_object  [SKETCH  Operation  Macro] 

[’g_index-switch  [^g_backquote-switchj]) 

uneval-object  [SKETCH  Operation] 

WHERE:  We  have  written  g^object  instead  of  ob^object  simply  to  emphasize  that  any 
LISP  value  can  be  considered  to  be  a  SKETCH  object  for  the  purposes  of 
uncval-objcct, 

RETURNS:  A  LISI*  value  which  when  cvaPed  will  evaluate  to  g_object.  More  impor¬ 
tantly,  when  prctty-prinPedy  re-read,  and  then  evaFed  this  value  will  evaluate 
to  g_object.  This  is  the  only  general  means  that  a  SKETCH  object  may  be 
transmitted  from  one  program  through  a  file  to  another  program. 

The  result  of  uneval-object  may  contain  calls  to  the  fictitious  macros 
backquote  and  comma,  which  will  pretty-print  as  ’  and  ,  respectively.  The 
argument  to  backquote  may  have  the  form  of  a  clotted  list,  as  in— 

[backquote  {...  .  [comma  ...))) 

Backquote  is  defined  as  a  macro,  and  its  |)re^>ence  also  signals  pretty-print  to 
process  the  list  specially. 

Comma  cannot  occur  outside  a  backquole^d  argument. 

A  SKETCH  object  which  is  indexed  by  having  a  has- name  attribute  will  be 
represented  by  an  expression  of  the  form— 

(s_type  ha$-naine  *s_name) 

which  evaluates  to  a  stub  for  the  object.  If  g_index-switch  is  absent  or  nil,  an 
exception  will  be  made  for  the  g_object  itself,  which  will  be  represented  as  a 
type  and  attribute  list  even  if  it  has  a  has-name  attribute.  However  no  such 
exception  will  be  made  for  the  attribute  values  of  g_object. 

By  using  these  rules,  it  is  possible  to  output  in  any  order  a  set  of  named 
objects  which  cross  reference  each  other,  and  get  the  cross  referencing  right 
when  the  objects  are  input  into  another  program  load. 

The  behavior  of  the  last  two  paragraphs  is  the  behavior  of  the  default 
uneval-object  functions  defined  by  declare-hunk-type  and  declare-vector-type. 
This  default  behavior  can  be  overridden  by  defining  special  uneval-object 
functions  for  a  particular  type. 

Sometimes  the  results  of  uneval-object  are  to  be  included  as  part  of  an  argu¬ 
ment  to  backquote.  In  this  case,  the  result  of  an  uneval-object  will  not  to  be 
evaluated  unless  it  is  a  call  to  the  comma  pseudofunction.  This  situation  is 
indicated  by  a  present,  non-m7  g_backquote-switch.  Otherwise,  uneval-object 
is  to  operate  normally,  assuming  that  the  result  will  be  evaluated  to  obtain 
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g_object.  For  example, 

{uneval- object  ’x  nil  t) 

will  return  just  x,  whereas— 

[uneval- object  ’x  nil  nil) 


will  return  ’x. 

EFFICIENCY;  This  maw:ro  compiles  more  efficient  code  if  g_object  is  an  expression  of  the 
form— 


(s_type  ...) 

whose  type  s_type  is  specified  at  compile  time. 


Also,  if  g_backquote-switch  is  not  given  or  has  a  known  value  {nil  or  f)  at 
compile  time,  and  if  g_object  does  not  have  the  form  — 

(s_type  ...), 

uncval-object  compiles  in-line  code  to  check  whether  g_object  is  a  number, 
string,  or  symbol,  and  returns  g_object  or  ’g_object  as  its  value  in  that 
case. 

UNEVAL-SWITCH:  If  an  attribute,  at_attribule.  of  an  object  of  type  ty_type  has  a  now- nit 
value  of 

[get’uneval- switch  ty_type  at_attribute), 

then  in  any  call  to  uneval- object,  this  value  will  control  the  uneval- 
objecting  of  the  attribute  value.  If  the  switch  is  no,  the  attribute  will 
not  be  included  as  part  of  the  unevaled  object.  If  the  switch  is  yes  or 
ni7,  the  attribute  will  be  included.  If  the  switch  is  another  symbol, 
that  symbol  will  be  taken  as  the  name  of  a  function  to  be  called  in 
place  of  uneval-object  to  uneval  the  attribute  value.  See  HAS- 
UNEVAL-SWITCH  under  an-  attribute-  descrip  tor . 


(unpre-evaluate-object  'ob_object)  [LISP  Function) 

USE  ONLY  WHEN:  Referencing  pre-evaluated  macro  arguments  in  calls  to  error  returned 
by  the  macro. 

RETURNS:  An  expression  which  crudely  attempts  to  undo  possible  pre-evaluation  of 
macro  arguments.  Returns— 

{uneval-object  ob^object) 
after  stripping  any  quote  function  therefrom. 


Printed  April  27,  1989 


CHAPTER  6 


CATALOGS 


1.  CATALOG  FILES  AND  FILE  CATALOGS.  A  catalog  file  is  a  file  that  stores  a 
sequence  of  LISP  and  SKETCH  objects  in  ASCII  text.  Each  object  is  represented  by  a 
LISP  expression  which  may  be  read  (by  the  LISP  read  function)  and  evaluated  (by  (he 
LISP  eval  function)  to  produce  the  object.  Virtually  any  LISP  or  SKETCH  object  can  be 
represented  in  this  manner. 

An  object  can  be  written  into  a  catalog  by  first  unevaluating  it  (using  the  SKETCH 
uneval-object  macro),  and  then  printing  the  result  (using  the  SKETCH  preity-print  macro, 
or  LISP  print  function). 

A  file  catalog  is  a-catalog  object  with  a  lias-file  attribute  that  is  a  symbol  naming  a 
catalog  file.  E.g.— 

[setq  the-catalog  [a-cataloy  lias-file  'my-file.ca)) 

where  my-file.ca  is  the  name  of  the  catalog  file.  Note  that  the  file  name  extension  xa  is 
preferred  for  catalog  files  (but  not  required). 

You  can  read  this  catalog  by— 

{setq  the-object  [read-catalog  the-catalog)) 

which  returns  the  next  object  in  the  catalog.  The  first  object  returned  from  a  new  cata¬ 
log  is  the  first  object  in  the  catalog.  If  you  want  to  reset  the  catalog  to  the  beginning, 
you  can  execute— 

[close-catalog  the-catalog) 

which  does  not  destroy  the  catalog  object,  but  does  release  operating  system  resources 
used  by  that  catalog,  and  causes  the  next  read-catalog  to  begin  back  at  the  beginning  of 
the  catalog.  There  is  no  explicit  open-catalog  operation:  it  is  implied  by  the  first  read  (or 
write)  of  a  catalog. 

Executing— 

[setq  the-object  [read-catalog  the-catalog)) 

when  the  catalog  is  positioned  at  its  end  will  return  the  symbol  end- of- catalog  as  the 
value  of  the-object. 

The-object  may  be  written  at  the  end  of  the  catalog  by— 

[write- catalog  the-catalog  the-object) 

Note  that  write-catalog  always  appends  to  the  end  of  the  catalog;  it  never  causes  informa¬ 
tion  to  be  lost  from  the  catalog.  When  you  are  done  writing  objects  into  the  catalog,  you 
should  use— 

[close-catalog  the-catalog) 

to  be  sure  everything  you  wrote  is  properly  transferred  to  disk. 
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After  you  start  reading  from  a  catalog,  you  should  not  write  to  the  catalog  until  you 
have  closed  it.  Similarly,  after  you  start  writing,  you  should  not  read  until  you  have 
closed  the  catalog. 

To  start  writing  at  the  beginning  of  a  catalog  you  first  truncate  the  catalog.  For 
catalog  files,  this  is  done  with— 

{setq  the-catalog  {new-catalog  ’my-file.ca)); 
which  truncates  my-file.ca  and  sets  the-catalog  to— 

{a-catalog  has-file  ^my-file.ca) 

It  is  also  possible  to  read  from  a  random  location  in  a  catalog  file.  To  find  the  loca¬ 
tion  of  the  last  object  read  from  the  catalog  by  read-catalog^  or  written  into  the  catalog 
by  xvriit-catalog,  use— 

the-location  {get-catalog-location  the-catalog)), 
after  which  the  last  object  can  be  read  at  any  later  time  by— 

{setq  the-object  {read-catalog  the-catalog  the-location)), 
regardless  of  where  the  catalog  is  positioned  when  this  last  statement  is  executed. 

If  you  look  at  the  value  of  the-location,  by  the  way,  you  will  find  it  to  be  a  list  of 
several  numbers.  Its  complexity  is  due  to  the  fact  that  objects  in  a  catalog  are  sometimes 
packed  (automatically)  by  referring  to  a  previous  object  in  the  catalog,  so  that  to  position 
to  an  arbitrary  object  in  a  catalog  requires  positioning  to  the  first  previous  unpacked 
object,  and  then  reading  forward  to  the  desired  object,  unpacking  as  you  read. 

When  opening  catalog  files,  the  directories  searched  are  those  in  the  list  of  directory 
names  (represented  by  symbols)  returned  by— 

{status  catalog-searcli-path) 
which  is  typically  set  by  placing  the  statement 

{sstatus  catalog-search-path  (|.  |  s_directory  ...)) 
in  the  sketch.rc  file  (which  is  loaded  whenever  sketch  is  started). 

2.  INDEX  CATALOGS.  An  index  catalog  permits  objects  in  a  second  catalog  to  be 
referenced  by  meaningful  names,  called  keys.  The  second  catalog  is  called  the  indexed 
catalog.  The  keys  are  defined  by  an  index  function  that  returns  the  key  of  an  object  when 
called  with  the  object  as  an  argument.  The  keys  become  the  locations  returned  by  get- 
catalog-location  and  used  by  read-catalog  when  these  functions  are  applied  to  the  index 
catalog. 

Suppose  we  have  a  catalog  file  named  mine.ca  containing  objects  some  of  which  have 
a  non- nil  has-id  attribute  that  we  wish  to  use  as  a  key.  Then  the  following  creates  the 
appropriate  index  catalog— 

{a-catalog  is-index-of  {a-catalog  has-file  ’mine.ca) 

has-index-function  \lambda  (x  y)  (has-id  x))) 

Here  the  indexed  catalog  is  {a-catalog  has-file  ’mine.ca),  the  value  of  the  is-uidex-of  attri¬ 
bute  of  the  index  catalog.  Also,  we  have  introduced  a  lambda  index  function,  instead  of 
just  using  has-id  directly,  because  has-id  is  actually  a  macro  (like  all  attribute  names), 
and  because  the  index  function  must  take  a  second  argument. 
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The  second  argunnent,  y,  is  the  number  (1,  2,  3,  ...)  of  the  object  in  the  indexed  cata¬ 
log.  So  to  use  the  object’s  number  as  its  key,  just  use  the  index  function  — 

’(/am6da  (x  y)  y). 

There  is  a  predefined  function  named  catalog-iuimber  that  equals  this  last  lambda,  so  the 
symbol  catalog-number  may  be  used  as  the  index  function  when  you  want  object  keys  to 
equal  the  number  of  the  object  in  the  indexed  catalog.  In  this  case— 

{read-catalog  ca^index-catalog  4) 
would  read  the  4’th  object  in  the  indexed  catalog. 

By  the  way:  one  must  not  replace  \la7nbda  ...)  by  if  {lambda  ...),  for  those  of  you 
who  know  that  this  trick  will  compile  the  lambda  function,  because  the  index  function 
should  be  something  we  can  save  in  a  file,  as  we  shall  see  in  a  moment. 

If  the  index  function  returns  nil  for  an  object,  that  object  has  no  key.  After  reading 
that  object  get-catalog-location  will  return  riiV,  which  cannot  be  passed  as  a  location  to 
read-catalog. 

The  default  index  function,  or  what  you  get  when  you  specify  nil  as  an  index  func¬ 
tion,  returns  a  key  only  for  objects  that  are  pairs  of  the  form  — 

{catalog-key  g_key). 

For  such  an  object  g«key  is  returned  as  the  key.  Putting  such  objects  at  selected  points 
in  a  catalog  file  enables  one  to  position  to  these  points.  .Vote  that  what  actually  appears 
in  the  catalog  file  is  the  quoted  list— 

'{catalog-key  g_key) 

At  the  end  of  every  catalog  the  symbol  end-of-catalog  appears  as  if  it  were  an  object 
in  the  catalog.  This  symbol  always  has  itself  as  its  key,  regardless  of  how  the  index  func¬ 
tion  is  defined.  That  is, 

{read-catalog  ca_index-catalog  'end-of-catalog) 

will  always  position  both  index  and  indexed  catalogs  at  their  ends  and  return  the  symbol 
end-of-catalog. 

Note  that  operations  on  an  index  catalog  are  equivalent  to  operations  on  its  indexed 
catalog,  except  that  object  location  values  are  different. 

If  you  use  one  of  the  index  catalogs  defined  above  that  index  mine.ca,  then  after  clos¬ 
ing  the  index  catalog  you  will  find  a  new  file,  mine.ci.  The  index  function  and  the  index 
itself  are  written  into  this  file  when  the  index  catalog  is  closed.  The  index  is  roughly  a  list 
of  triples  each  consisting  of  a  key,  the  number  of  an  object  in  the  indexed  catalog,  and  the 
location  of  the  object  in  the  indexed  catalog.  The  index  may  not  be  complete.  Later,  if 
another  index  catalog  is  defined  that  indexes  mine.ca  with  the  same  index  function,  the 
mine.ci  file  will  be  used  to  read  the  index,  and  save  the  time  of  having  to  read  the  entire 
mine.ca  file  to  rebuild  the  index.  Also,  no  index  function  need  be  specified  for  the  index 
catalog  if  mine.ci  exists;  it  will  be  read  from  mine.ci. 

You  can  provide  the  name  of  a  file  to  serve  as  mine.ci  for  any  index  catalog.  It  is  a 
symbol  which  is  the  value  of  the  index  catalog’s  has- index- file  attribute.  Note  that  the 
index  stored  in  one  of  these  files  may  be  incomplete,  as  the  index  is  built  incrementally  as 
it  is  needed,  and  not  completed  until  the  end  of  the  indexed  catalog  is  read.  See  HAS- 
INDEX-FILE  under  a-catalog  \n  the  GLOSSARY. 
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When  index  files  are  being  used,  keys  must  be  objects  that  will  equal  themselves 
when  printed  and  re-read.  Integers,  symbols,  character  strings,  and  lists  of  these  will 
work.  Floating  point  numbers  that  originated  when  character  strings  with  5  or  fewer 
digits  were  read  into  the  computer  may  also  work. 

If  you  use  an  index  catalog  to  w'rite  a  catalog  file  like  mine.ca,  the  index  file,  mine.ci, 
will  be  made  when  the  index  catalog  is  closed.  Once  mine.ci  is  completed,  the  index  func¬ 
tion  is  actually  never  needed  again.  In  particular,  it  may  be  a  symbol  that  has  no  func¬ 
tion  definition  in  environments  in  which  mine.ca  is  read  with  an  index  catalog. 

3.  INCLUDED  CATALOGS. 

4.  FILTER  CATALOGS. 

5.  RANDOM  PORTS. 

6.  TAPE  VOLUMES. 


7.  HITLIST. 

(1)  Finish  tutorial  documentation. 

(2)  Implement  tape  volumes. 

(3)  Possibly  improve  packing  algorithm. 

8.  GLOSSARY. 


(a-catalog  [has-filt  ’s_file-name]  'SKETCH  Object] 

\has-fiUcr  ‘(u_function  ,ca_input-catalog)) 

\i$-xndex-oJ  ca_indexed-file] 

\has-xndcx-filc  ’s_index-file) 

\ha$-xndex- Junction  *u_index-function]) 


(has-file  ^ca_catalog) 

(has-filter  *ca_catalog) 
(is-indcx-of  *c2L-catalog) 
(has-index-file  ’ca_catalog) 
(has-index-function  ’ca_catalog) 


[SKETCH  Attribute  Macro] 
[SKETCH  .Attribute  Macro] 
[SKETCH  Attribute  Macro] 
[SKETCH  Attribute  Macro] 
[SKETCH  Attribute  Macro] 


catalog-key  [LISP  Symbol] 

(catalog-number  ob_x  x_number)  [LISP  Function] 

VALUE:  A  catalog  object  that  may  be  used  to  read  or  write  LISP  objects.  There  are 
several  different  kinds  of  catalogs,  distinguishable  by  their  attributes. 

HAS-FILE:  A  file  catalog  has  a  file  name  in  the  lias-file  attribute.  The  file  contains  a 
sequence  of  LISP  expressions  which  can  be  read  and  then  eva/uated  to  produce 
LISP  values.  These  LISP  expressions  may  be  packed:  each  expression  may  be 
represented  in  a  special  notation  that  describes  only  its  differences  from  the 
previous  expression  in  the  file. 


A  file  catalog  can  be  written  as  well  as  read.  The  values  written  are  converted 
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using  uiieval-object  into  an  expression  that  will  eua/uate  into  the  value  being 
written.  The  values  written  are  packed,  but  after  packing  50  values  a  value  is 
intentionally  left  unpacked  to  speed  repositioning  when  reading  the  catalog. 

H.AS-FILTER:  The  value  of  this  attribute  consists  of  a  two  element  list,  or  pair,  of  the 
form- 

(ujunction  cajnput-catalog) 

The  function  is  a  function  of  one  variable  which  is  applied  to  each  value 
read  from  ca_input-catalog  to  produce  an  output  value  for  the  current 
catalog.  If  the  function  returns  the  symbol  ^please-ignore,  the  correspond¬ 
ing  cajnput-catalog  value  is  ignored. 

A  filter  catalog  cannot  be  written. 

IS-INDEX-OF: 

K.\S- 1 NDEX-  FUNCTI  ON : 

H.>\S-INDEX-FILE:  The  value  of  the  is^index-of  attribute  is  a  catalog,  cajndexed-catalog, 
called  the  indexed  catalog.  The  current  catalog  is  called  the  index  cata¬ 
log.  Operations  on  the  index  catalog  are  equivalent  to  operations  on 
the  indexed  catalog,  except  for  operations  involving  locations.  The 
locations  of  an  index  catalog  are  keys  determined  by  u Jndex-function 
This  function  is  called  by- 

[funcall  u  Jndex-function  ob_object  x_number) 

where  ob_object  is  the  x_number’th  object  in  cajnclexed-catalog.  The 
function  (which  must  not  have  side  effects)  returns  a  key  which  is  used 
to  name  the  location  of  the  object  in  the  index  catalog.  The  function 
may  also  return  nil  to  indicate  that  the  object  does  not  have  a  well 
defined  location  in  the  index  catalog. 

Thus  if  ujndex-function  equals— 

[lambda  (x  y)  y), 

the  x_number*th  object  in  the  indexed  catalog  will  have  x_number  as 
its  key.  The  function  catalog^number  is  defined  to  be  equal  to  this  par¬ 
ticular  function,  and  is  more  mnemonic. 

The  keys  must  be  lisp  objects  that  equal  themselves  when  printed  and 
re-read.  E.g.  integers,  symbols,  character  strings,  and  lists  of  such. 
The  keys  must  be  unique:  a  non-unique  key  used  as  a  location  for  the 
index  catalog  will  locate  any  of  the  several  objects  in  the  indexed  cata¬ 
log  that  have  that  key.  The  symbol  end- of- catalog  is  automatically  the 
key  of  the  end  of  the  end- of- catalog  symbol  returned  at  the  end  of 
cajndexed-catalog  (regardless  of  the  definition  of  ujndex-function), 
and  must  not  be  a  key  of  any  object  in  ca_inde.\ed-catalog. 

If  the  has-index-fxinction  attribute  is  nxl^  the  key  for  any  object  of  the 
form  — 
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{catalog-key  g_x), 

will  be  g_x,  while  no  other  ol)jects  will  have  a  key. 

The  index  catalog  keeps  an  index  table  that  translates  keys  into  loca¬ 
tions  in  the  indexed  catalog.  This  table  may  be  incomplete  if  the  entire 
indexed  catalog  has  not. been  read  and  translated  into  keys.  If  a 
request  is  made  to  locate  to  an  object  with  a  key  not  yet  in  the  index 
table,  the  remainder  of  the  indexed  catalog  is  read  until  the  object  with 
the  key  is  found,  or  until  the  end-of-catalog  is  reached,  in  which  case  an 
error  is  signaled. 

If  s_index-file,  the  has- index- file  attribute,  is  non-m7  and  names  a  read¬ 
able  file,  then  when  the  index  is  first  needed,  the  l\as-index-function 
value  and  the  index  itself  will  be  read  from  s_index-file.  The  has- 
index- function  value,  which  must  be  a  symbol  or  a  printable  lambda 
list,  will  be  read  from  the  beginning  of  s_index-file.  The  index  will  then 
be  read. 

There  are  two  cases  when  the  contents  of  s_index-file  are  ignored. 
First,  if  the  hos-index-ftinction  has  a  non-/u7  value  before  the  file  is 
read,  and  this  value  is  not  equal  to  the  index  function  read  from  the 
file,  then  it  is  assumed  that  the  contents  of  the  file  are  not  valid  for  the 
current  application.  Second,  if  the  indexed  catalog  has  a  has-file  attri¬ 
bute  whose  file  has  been  modified  more  recently  than  s_index-file,  it  is 
assumed  that  the  index  stored  in  the  file  is  not  valid,  though  the  index 
function  read  will  still  be  used  to  replace  a  nil  has-index-function  value. 

If  the  has-index-file  attribute  is  non-?2i7  and  s_index-file  is  writable  or 
creatable  when  the  index  catalog  is  closed,  the  has-index-function  attri¬ 
bute  and  the  index  itself  are  written  into  that  file,  unless  they  are  both 
identical  to  what  was  read  from  the  file  previously.  In  particular,  if  the 
index  catalog  was  being  used  to  write  the  indexed  catalog,  the  complete 
index  will  be  written.  However,  if  the  index  file  was  merely  being  used 
to  read  the  indexed  file,  and  if  end-of-catalog  had  not  been  reached, 
then  only  a  partial  index  will  be  written. 

In  searching  for  the  directory  containing  s_index-file,  the  same  pro¬ 
cedure  is  used  as  when  searching  for  a  catalog  file. 

If  the  has-index-file  attribute  is  ni7,  and  the  indexed  catalog  is  a  file 
catalog  whose  file  name  ends  in  .ca,  then  a  file  name  made  by  replacing 
the  .ca  by  .ci  will  be  used  as  if  it  were  the  value  of  the  has-index-file^ 
unless  such  a  file  already  exists  and  contains  a  has-index- function  value 
that  disagrees  with  a  non- 711/  initial  value  of  that  attribute  for  the  index 
catalog. 

If  no  file  is  available  for  use  as  the  index  file,  the  index  is  lost  when  the 
index  catalog  is  closed.  If  the  index  catalog  is  not  closed,  any  index 
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constructed  in  MOS  memory  that  would  have  been  written  out  were 
the  catalog  closed  will  be  lost.  However,  when  SKETCH  exits,  all  open 
index  catalogs  will  be  automatically  closed. 

WARNING:  When  using  a  .ct  file  with  a  .ca  file  that  includes  other  catalog  files,  the  index 
will  not  be  automatically  invalidated  when  the  included  catalog  files  are 
changed.  To  invalidate  the  index  the  user  should  touch(l)  lhe  including  .ca 
file. 

NOTE:  The  has-tndex-filc  and  .ct  files  can  be  used  by  several  SKETCH  processes  at  once, 
and  are  (hopefully)  protected  against  the  various  abnormal  states  that  may  arise 
during  such  use. 

(a-tape-volume  [SKETCH  Object] 

has-tape-format  ’(.\_record_length  ...) 

[/ia5-name  ’s^name] 

[has- drive  ’x_drive] 

[has- file-number  ’x_file-n umber] 

[has-record-numher  ’x^record-number] 

[is-modified  ’s_modified-switch]) 

WARNING:  Tape  volumes  and  operations  thereupon  are  not  yet  implemented. 

USE:  A-tape-volume  is  an  object  describing  the  format  of  a  magnetic  tape.  The  contents 
of  the  tape  are  not  described  in  detail:  only  the  format. 

This  object  is  stored  in  the  file  named  s_name  (accessible  using  the  data-searcli- 
path  directory  list.  The  optional  attributes  (including  has-nanie)  are  supplied  by 
SKETCH  software  when  the  tape  volume  is  mounted  (see  mount-tape)  and  are  not 
part  of  the  object  stored  in  the  s_name  file. 

HAS‘TAPE-FORMAT:  This  list  describes  the  tape  format.  It  is  a  list  with  one  element  for 
each  file  on  the  tape.  That  element  is  the  record  size  in  bytes  of 
records  in  the  file. 

For  input  files,  the  record  size  may  be  an  overestimate:  the  max¬ 
imum  possible  size  in  bytes  of  any  record  in  the  file.  For  output 
files  all  records  will  be  exactly  the  given  size. 

Files  on  the  tape  are  separated  by  file  marks.  When  a  tape  is  writ¬ 
ten,  two  consecutive  file  marks  are  written  after  the  last  file. 

HAS-NAME:  S_name  serves  as  a  file  name  for  a  file  containing  nothing  but  the  a-tape- 
volume  object.  The  file  named  is  found  by  searching  the  [status  catalog- 
search-path)  list  of  directories. 

The  file  named  by  s_name  is  called  the  volume  object  file  for  the  tape 
volume.  It  is  read  when  the  tape  is  mounted,  and  may  be  written  when  the 
tape  is  dismounted  if  its  has-tape-files  attribute  has  been  modified. 

S_name  is  also  used  as  the  name  of  the  volume  inside  the  LISP  environment. 
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It  is  strongly  recommended  that  s_name  end  with  the  extension  standing 
for  "tape  volume". 

HAS-DRIVE:  A  symbol  or  number  naming  the  tape  drive.  The  following  are  standard  — 

0—9  Magnetic  tape  drive  0  through  9. 

HAS-FILE-NUMBER:  The  number  (l,  2,  ...)  of  the  file  in  which  the  tape  is  currently  posi¬ 
tioned. 

R\S-RECORD-NUMBER:  The  number  (l,  2,  ...)  of  the  record  just  before  which  the  tape  is 

currently  positioned. 

IS-MODIFIED:  Non-ni7  if  the  has-tapc-format  list  has  been  modified  since  the  tape  volume 
was  mounted. 

“catalog  file*’  {SKETCH  Term] 

.ca  [UNIX  File  Extension) 

FILE  FORMAT;  A  catalog  file  is  a  file  created  by  nexv-catalog,  wrife-cafalog,  and  close- 
catalog.  It  holds  a  sequence  of  LISP  values,  including  SKETCH  objects 
such  as  an-array  objects.  Each  LISP  value  is  represented  by  a  LISP 
expression  which  can  be  read  and  then  evaluated  to  produce  the  value. 

The  preferred  extension  for  catalog  files  is  .ca. 

(catalog-pack  ’g_next-expression  ’g_last-expression)  [LISP  Function] 

USE  ONLY  WHEN:  Maintaining  catalog  package. 

RETURNS:  The  packed  version  of  the  unpacked  g_next-expression  in  the  context  where 
the  value  returned  is  to  be  written  into  a  packed  file  of  LISP  expressions,  and 
the  unpacked  version  of  the  previous  expression  written  is  g_last-expression. 

NOTE:  If  g_next-expression  cannot  be  packed,  it  is  returned.  Packing  will  have  occurred 
only  if  the  value  returned  is  not  g_next-expression. 

[status  catalog-search-path)  [LISP  Function] 

[sstatus  catalog-search-path  (s_directory  ...))  [LISP  Function] 

catalog-key  [LISP  Symbol] 

VALUE:  The  list  (s_directory  ...)  is  a  list  of  the  names  of  directories  which  are  searched 
for  catalog  files  to  be  input.  The  first  directory  named  in  the  list  is  the  place 
where  new  catalog  files  are  created  (unless  the  name  given  the  new  file  contains 
a  directory  name). 
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(catalog-unpack  ’g_next-expression  ’gjast-expression)  LISP  Function) 

USE  ONLY  WHEN:  Maintaining  catalog  package. 

RETURNS:  The  unpacked  version  of  the  packed  g_next-expression  in  the  context  where 
g^next-expression  has  been  read  from  a  packed  file  of  LISP  expressions,  and 
the  unpacked  version  of  the  previous  expression  read  is  gjast-expression. 

NOTE:  If  g^next-expression  was  already  unpacked,  it  is  returned.  Unpacking  will  have 
occurred  only  if  the  value  returned  is  not  g_next-expression. 

xi  [UNIX  File  Extension) 

FILE  FORMAT:  A  catalog  index  file  associated  with  a  .ca  file.  See  has-index-file  under  a- 
catalog. 

(close-catalog  'ca_catalog)  .LISP  Function) 

SIDE  EFFECT:  Closes  the  catalog,  flushing  all  information  stored  in  ports  associated  with 
the  catalog. 


(copy-catalog  ’g_input  ’g_output  [’(g_key  ...)])  -LISP  Function] 

(append-catalog  ’gjnput  ^g_output  [’(g_key  ...)])  LISF^  Function] 

WHERE:  G_input  is  either  a-calatog,  or  a  symbol  naming  a  file  from  which  the  catalog— 

{a-catalog  has-file  gjnput) 
is  made;  and  g_output  is  similar. 

RETURNS:  The  number  of  items  copied. 

SIDE  EFFECT:  Items  are  read  from  the  input  catalog  and  written  to  the  output  catalog 
until  and  end- of- catalog  is  read.  Both  catalogs  are  then  closed. 


If  g_output  is  a  symbol,  copy-file  uses  new-catalog  to  create  the  output 
catalog  and  truncate  the  file,  whereas  append-catalog  simply  creates  the 
output  catalog  without  truncating  the  file,  and  thereby  appends  to  the  file. 


If  ’(g— key  ...)  is  given,  the  catalogs  must  be  in  indexed  catalog  (if  it  is  not, 
they  are  replaced  by  index  catalogs  whose  is-index-of  attributes  are  the 
original  catalogs).  The  input  is  copied  by  first  copying  the  object  at  loca¬ 
tion  g_key  and  all  objects  following  it  that  have  no  key;  then  doing  the 
same  for  the  object  whose  location  is  the  next  key  in  the  ’(g_key  ...)  list, 
and  so  forth  to  the  end  of  the  list.  If  an  object  at  location  g_key  is  not  of 
the  form— 


[catalog-key  ...) 

then  the  object— 

[catalog-key  g_key) 

is  output  just  before  it  (but  this  last  object  is  not  included  in  the  returned 
count  of  objects  copied). 
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(5/0/U5  data-search-path)  [LISP  Function} 

data-search-path  {s_directory  ...))  [LISP  Function) 

VALUE:  The  list  (s_directory  ...)  is  a  list  of  the  names  of  directories  which  are  searched 
for  data  files  to  be  input.  The  first  directory  named  in  the  list  is  the  place  where 
new  data  files  are  created  (unless  the  name  given  the  new  file  contains  a  direc¬ 
tory  name). 

(dismount-tape  [’x_drive])  [LISP  Function] 

(dismount-tape  [*s_volume-name|)  [LISP  Function) 

SIDE  EFFECT:  Dismounts  the  indicated  a- tape- volume  oh]tcV.  i.e.  undoes  mount-tape. 

Closes  the  drive.  Writfi^  the  a-tape-volume  object  back  to  its  file  if  it  has 
been  modified. 

(get-catalog-keys  ’ca_index-catalog)  [LISP  Function] 

RETURNS:  The  list  of  all  keys  defined  for  an  inde.x  catalog. 

SIDE  EFFECT:  Reads  to  the  end  of  the  catalog. 

(get-catalog-location  *ca_catalog)  [LISP  Function! 

RETURNS:  The  location  of  the  last  value  read  from  or  written  to  ca_catalog.  This  loca¬ 
tion  is  some  LISP  value  that  can  be  understood  by  read-catalog. 

(get-random-port  *p_port  ['gjocation  ’s_direction  [LISP  Functionj 

[*(s_directory-name  •..)]]) 

USE  ONLY  WHEN:  Copying  between  memory  and  random  locations  in  the  file  system  or 
on  magnetic  tape. 

WHERE:  Gjocation  specifies  a  byte  location  within  a  file.  It  has  one  of  the  following 
forms: 

s_file-name 
(s_file-name  [x_offset|) 

(s_file-name  end-of-file) 

(s_volume-name  x_file  x_record  [x_offset]) 

(s_volume-name  end- of- volume) 

(s_volume-name  x_file  end-of-file) 

S_file-name  is  the  name  of  a  file  that  is  searched  for  in  the  directories 
(s_directory  ...).  The  directory  list  defaults  to  (status  data-search-path).  If  an 
output  file  does  not  already  exist  in  one  of  these  directories,  it  is  created  in  the 
first  directory  in  the  list  (unless  the  output  file  name  contains  a  directory  name: 
see  the  write  mode  of  search-path). 

S_volume-name  is  the  name  of  a  tape,  x_file  the  number  of  a  file  on  that  tape 
(1,  2,  3,  ...),  and  x_record  the  number  of  a  record  in  that  file  (1,  2,  3,  ...). 

X^ofTset  is  the  number  of  bytes  in  the  file  or  tape  record  before  the  first  byte  to 
be  read  or  written.  For  a  file,  end-of-file  denotes  the  x^oflset  value  to  position 
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to  the  end  of  the  file  (which  is,  in  fact,  the  current  length  of  the  file). 

For  a  tape  volume  end- of- volume  denotes  the  x_file  and  x_record  values  neces¬ 
sary  to  start  a  new  file  at  the  end  of  the  volume,  while  end-of-file  denotes  the 
x_record  value  necessary  to  add  a  record  to  the  end  of  the  file  designated  by 
x_file.  In  these  cases  the  port  must  be  for  writing,  and  not  for  reading. 

’s_direction  is  either  ’read  or  ^ write, 

RETURNS:  A  port  positioned  to  the  location  g_location,  or  nil  if  it  is  not  possible  to  pro¬ 
duce  such  a  port,  or  if  g_location  itself  is  missing  (see  SIDE  EFFECT  for  this 
last  case). 

The  port  is  suitable  for  reading  if  s^direction  is  Vend,  or  for  writing  if 
s_direction  is  'write. 

SIDE  EFFECT:  The  random  i/o  package  keeps  a  cache  of  ports  which  it  repositions  and 
passes  to  users.  P_port  is  a  user  port  being  returned  to  this  cache. 
Report  may  be  nil  if  no  port  is  being  returned. 

The  value  of  get-randoni-port  is  a  port  taken  from  the  cache  and  posi¬ 
tioned  to  gjocation.  If  g_location  is  missing  no  port  will  be  taken  from 
the  cache  and  the  value  returned  will  be  nil.  A  call  with  missing 
g_location  may  be  used  to  return  a  previously  acquired  port. 

NOTE:  The  user  may  reposition  a  returned  port  to  a  different  offset,  or  find  its  current 
offset.  Other  operations,  aside  from  reading  and  writing,  should  not  be  per¬ 
formed  on  the  port. 

NOTE:  The  offset’s  in  locations  are  identical  to  the  port  offsets  that  can  be  changed  and 
inspected  by  fseek.  This  means  that  each  tape  record  is  treated  like  a  complete 
file  all  by  itself,  with  offset  0  corresponding  to  the  beginning  of  the  record.  The 
port  for  a  tape  location  will  suffer  an  end-of-file  at  the  end  of  the  record. 

NOTE:  The  user  may  not  posses  multiple  ports  referencing  the  same  tape  volume. 

BUG:  If  you  unlink  a  file  for  which  you  have  recently  had  a  random  port,  and  then  get  a 
random  port  with  the  same  file  name,  the  port  you  get  may  be  for  the  old  file, 
which  is  now  nameless.  This  is  because  the  port  associated  with  the  file  name  is 
not  closed  and  reopened.  However,  you  can  truncate  a  file  successfully  without 
unlinking  it,  because  the  ports  are  drained  (but  not  closed)  when  they  have  no 
users. 
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(get-random-port-location  ’p_port)  (LISP  Function] 

USE  ONLY  WHEN:  Copying  between  memory  and  random  locations  in  the  file  system  or 
on  magnetic  tape. 

RETURNS:  The  current  location  of  p_port,  assuming  the  latter  was  gotten  by  a  call  to 
get-random-port.  This  location  is  one  of  the  forms  where  x^offset  is  an  expli¬ 
cit  number. 

(has-function  'ca^catalog)  [SKETCH  Attribute] 

USE  ONLY  WHEN:  Defining  new  types  of  catalog. 

VALUE:  The  has-function  attribute  is  automatically  set  from  the  other  attributes  when  it 
is  gotten.  Thus  most  users  need  not  worry  about  it. 

The  function  calls 

[read-catalog  ca^catalog  [g^location]) 

[write-catalog  ca_catalog  g^value) 

[get‘ catalog- location  ca_catalog) 

[close-catalog  ca_catalog) 

normally  translate  into 

(funcall  [has-function  ca_catalog)  Vend  ca_catalog  [g_location]) 

(funcall  [has-function  ca_catalog)  ^write  ca_catalog  g_value) 

(funcall  (Aas-/unc/ion  ca_catalog)  'locate  ca_catalog) 

(funcall  [has-function  ca_catalog)  'close  ca_catalog) 

The  call 

(funcall  (Aa5-/unc/ion  ca_catalog)  Vead  ca_catalog) 
must  return  'end- of- catalog  at  an  end  of  file. 

Some  possible  values  for  the  has-function  attribute  are  'file-catalog,  which  uses 
the  has-file  attribute,  'filter- catalog  which  uses  the  has-filter  attribute,  and 
' index- c at alo g  yfhich  uses  the  is-index-of  attribute. 

When 

(funcall  [has-function  ca_catalog)  'read  ca_catalog) 

returns  a  list  of  the  form 

[please- include  ca_included-catalog) 

the  read-catalog  function  alters  ca_catalog  so  that  future  requests  to  read  it  will 
return  values  from  cajnclude-catalog  until  the  end  of  the  latter. 
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(has- include  ’ca^catalog)  [SKETCH  Attribute] 

USE  ONLY  WHEN:  Maintaining  catalog  package. 

VALUE:  When  another  catalog  is  being  included  in  this  catalog,  a  two  element  list  of  the 
form- 


(ca_included‘Catalog  gjocation-of-included-catalog) 

The  location  is  the  location  within  this  catalog  of  the  value  of  the  form- 


{pleasc-include  ca_included-catalog) 

which  caused  the  inclusion  to  start.  If  there  is  no  inclusion  currently  in  pro¬ 
gress,  the  has-include  attribute  value  is  nil. 

(lookat-tape  px^drive))  [LISP  Function) 

(lookat-tape  [’s_volume-namej)  [LISP  Function] 

RETURNS:  The  a-tape-volurne  object  for  the  given  drive  number  or  volume  name,  if  one 
is  mounted.  When  this  prints  its  has-drive,  haS’file-mimber,  and  has-record- 
vumbcr  attributes  tell  the  drive  and  current  position. 


(make-catalog-index  ’g_catalog  [’s_index-file])  [LISP  Functioa] 

WHERE:  G_catalog  is  either  a-catalog  or  a  symbol  naming  a  file  from  which  the  catalog  — 

{(I’Catalog  liaS’file  gjnput) 


is  made. 


If  s_index-file  is  not  given,  g_catalog  must  be  a  symbol  ending  in  .ca,  or  a  has- 
file  catalog  with  a  has-file  attribute  which  is  a  symbol  ending  in  .ca,  and  this 
symbol  with  .ca  replaced  by  .ci  will  be  used  as  the  s_index-file  value.  The  has- 
index-function  is  taken  if  available  from  the  previous  version  of  sjndex-file,  or 
is  nil. 

RETURNS:  The  number  of  items  read  from  g^catalog. 

SIDE  EFFECT:  Builds  an  index  file  named  s_index-file  suitable  for  use  as  the  has-index-file 
attribute  of  an  index  file  whose  is-index-of  attribute  is  g_catalog. 
S_index-file  is  initially  truncated. 
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(mount-tape  ’s_volume-name  [’x^drivej)  [LISP  Function) 

RETURNS:  The  a- tape- volume  oh]tci  for  the  tape  volume  mounted. 

SIDE  EFFECT:  Mounts  the  a-tape-volume  object  indicated.  Reads  this  object  from  the  file 
named  s_volume-name.  .Assigns  a  has-name  attribute  to  the  object  (which 
is  not  assigned  in  the  file’s  version  of  the  object).  Assigns  the  drive  to  the 
object  and  opens  the  drive. 

(new-catalog  ’s_file-name)  [LISP  Function] 

RETURNS:  A  new,  empty,  catalog  with  has-file  attribute  value  s_file-name.  If  any  previ¬ 

ous  catalog  existed  with  that  name,  it  is  emptied  (its  file  is  truncated). 

(new-data-file  ’s_file-name)  [LISP  Function] 

RETURNS:  The  name  of  the  file  found  by 

{search-path  (status  data-search-path)  s_file-name  ’a) 

SIDE  EFFECT:  The  file  whose  name  is  returned  is  truncated  to  0  length  if  it  exists,  or 
created  as  a  file  of  0  length  if  it  does  not  exist. 

(read-catalog  ’ca^catalog  [’g_location|)  [LISP  Function] 

please-ignore  [LISP  Symbol] 

(please-include  ca_catalog)  [LISP  List] 

RETURNS:  Returns  the  next  value  read  from  ca_catalog.  If  gjocation  is  given,  it  must 
be  a  location  returned  from  the  call 

[get- catalog-location  ca_catalog) 

and  the  value  returned  will  be  the  value  at  the  given  gjocation. 

At  the  end  of  ca_catalog,  the  symbol  end-of-catalog  W\\\  be  returned. 

NOTE:  If  the  symbol  please-ignore  is  to  be  returned  from  read-catalog^  that  function 
skips  that  value  and  continues  to  the  next  value  in  the  catalog. 

NOTE:  If  a  value  of  the  form 

[please-include  ca^included-catalog) 

is  to  be  returned  from  read-catalog^  that  function  instead  returns  the  first  value 
from  cajncluded-catalog  (using  read-catalog  recursively  to  read  that  catalog), 
and  in  subsequent  calls  keeps  returning  values  from  ca_included-catalog  until  the 
symbol  end-of- catalog  is  to  be  returned.  Then  the  read-catalog  function  returns 
instead  the  next  value  read  from  ca^catalog. 
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.tv  [UNIX  File  Extension] 

FILE  FORMAT:  These  filee  contain  a-tape-voluine  object  describing  a  single  tape  volume. 
There  is  only  one  such  object  per  file. 

(write-catalog  ’ca^catalog  ^g_value)  [LISP  Function] 

SIDE  EFFECT:  Writes  g_value  at  the  end  of  ca_catalog.  Notice  that  no  part  of 
ca^catalog  can  be  overwritten  (but  see  new-catalog,  which  truncates  cata¬ 
log  files).  The  actual  writing  operation  is  essentially  done  by  executing- 

[prctty-print  (uneval-object  g_valiie)  ...) 


Printed  April  27,  1989 


CHAPTER  7 


ARRAYS 


1.  ROADMAP  Since  the  tutorial  has  not  yet  been  written,  the  following  will  have  to 
do.  Start  with  the  an-array  glossary  entry,  and  then  read  the  sar_demo.ou  demonstra¬ 
tion  output  listing,  looking  up  the  glossary  entries  as  you  go.  C  programmers  should 
them  read  the  sar^array  glossary  entry,  followed  by  all  the  subsequent  entries  for  names 
beginning  with  sar_  or  SAR_. 

2.  HITLIST 

(1)  VV’rite  tutorial  documentation. 

(2)  Possibly  change  prepare-array  to  use  array- copy-ejponerit  whenever  making  a  new 
army,  even  if  it  is  the  same  element  type  as  the  old  array.  Thi.s  means  revising 
many  calls  to  prepare-array  to  have  an  explicit  exponent. 

(3)  Dcline  compare-object  so  constant  arrays  may  have  has-naine  attributes.  In  general, 
compare-object  currently  makes  no  sense  for  arrays. 

(3)  Document  sar_slice,  sar_duplicate,  sar_aduplicate. 

(o)  Change  sar_print  output  format  to  produce  a  LISP  expression. 

(6)  Fix  the  bug  in  Tnirror-array  involving  dimension  parity. 

3.  GLOSSARY. 

(altered-duplicate-of-array  ’ar^array  ’ty_element-type  [LISP  Function] 

[’x^exponent  [’x_offset  [’x^sizej]]) 

USE  ONLY  WHEN:  Creating  from  an  array  of*  structures  an  array  of  substructures,  or 
numbers.  Also  occasionally  used  to  change  the  apparent  element  type 
of  an  array. 

RETURNS:  A  new  array  which  is  like  that  returned  by  slice-of-array  but  has  a  change  of 
element  type  to  ty_element-type  and  exponent  to  x_exponent.  The  parent 
and  slice  of  the  new  array  are  equal,. and  are  equal  to  the  current  slice  of 
ar_array  if  no  x_offset  or  x^size  are  given.  Here  equality  means  that  the 
addresses  of  the  elements  with  the  same  subscripts  are  the  same,  but  the  the 
element  types  and  exponents  need  not  be. 

If  x_offset  is  given  but  x_size  is  not,  the  addresses  of  the  new  array  elements 
are  offset  from  the  addresses  of  the  corresponding  ar_array  elements  by 
.x^offset  times  the  size  of  the  new  array  elements  (determined  by  ty_element- 
type).  The  elements  of  the  new  array  must  lie  within  the  corresponding  ele¬ 
ments  of  the  old  array. 
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If  both  x^ofTset  and  x_size  are  given,  a  new  X  dimension  of  size  x^ize  is 
created  for  the  new  array,  such  that  the  new  array  elements  with  given  Y,  Z, 
T,  U,  V  subscript  values  form  a  contiguous  block  of  memory  within  an  ele¬ 
ment  of  ar_array  whose  X,  Y,  Z,  T,  and  U  subscripts  respectively  equal  the 
Y,  Z,  T,  U,  and  V  subscripts  for  the  new  array.  In  other  words,  the  dimen¬ 
sions  of  the  old  array  are  pushed  down  in  forming  the  new  array:  X  becomes 
Y,  Y  becomes  Z,  Z  becomes  T,  T  becomes  U,  U  becomes  V,  and  V  is  dis¬ 
carded.  The  new  array  elements  with  0  X  subscript  have  addresses  offset 
from  the  old  array  elements  that  contain  them  by  x_offset  times  the  size  of 
the  new  array  elements  (determined  by  ty_element-type).  SIDE  EFFECT 
The  elements  of  ar_array  are  first  allocated,  if  this  has  not  already  been  done. 

DEFAULTS:  X_exponent  defaults  to  0. 

BUG:  The  size  in  bits  of  the  new  array  elements  must  be  an  exact  divisor  of  the  size  of 
the  old  array  elements.  This  restriction  is  unfortunate,  and  is  a  consequence  of 
storing  the  has-incremtnts  attributes  in  units  of  one  element  size.  No  fix  is  likely. 

NOTE:  The  new  array  elements  share  memory  with  the  corresponding  elements  of 
ar_array,  so  that  changes  to  these  ar_array  elements  will  change  the  correspond¬ 
ing  new  array  elements  and  vice  versa. 

NOTE:  The  has-been-changed  and  is-readonly  attributes  of  the  new  array  are  set  to  the 
corresponding  attributes  of  the  old  array.  The  is-irnmovable  attribute  is  set  to 
nii 

(an-array  has-sizes  ’(x_xsize  [x_ysize  ...])  [SKETCH  Type  Macro] 

[has-element-type  Yy_element-type] 

[has-expo7ient  \'_exponent| 

[by- expression  'g_expression| 

[by-value  *g_value| 

[has-array-file  'g_array-file| 

[has-offsets  '(n_xoffset  [n^yoffset  ...])] 

[has-scales  *(n_xscales  [n_yscales  ...])]) 

(an-array  has-parent-sizes  ’(x_xparent-size  [x_yparent-size  ...j)  [SKETCH  Type  Macro] 
[has-parent-increments  '(x_xparent-increment  [x_yparent-increment  ...]) 
[has-parent-offsets  ’(n_xparent-offsets  [n_yparent-offsets  ...]) 

[has-parent-scales  *(n_xparent-scales  [n_yparent-scales  ...]) 

[has- desired-sizes  *(x_xdesired-sizes  [x_ydesired-sizes  ...]) 

[has-destred-origins  ’(x_xdesired-origins  [x_ydesired-origins  ...]) 

[/ias-siep5  ’(x^xsteps  [x_ysteps  ...]) 

[has-element-type  ’ty_element-type] 

[has-exponent  ’x_exponent] 

[by- expression  ’g_expression] 

[by-value  ’g_value] 

[has-array-file  ’g_array-file] 

[is-readonly  *g_readonly-switch] 

[is-irnmovable  'g_im movable-switch]) 

(an-array  *ar_prototype  [SKETCH  Type  Macro] 

[do-shar e-elements  g_share-elements] 

...) 
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(allocate- array  ’ar_array) 


[LISP  Macro! 


an-array 

ar_ 

car_ 

sar_ 

lar_ 

far_ 

dar_ 

ubar_ 

ucar_ 

usar_ 

ular_ 

(has-element-type  ’ar^array) 
(has-exponent  ’ar_array) 


[SKETCH  Type  Object) 
[Argument  Prefix] 
[Argument  Prefix] 
[Argument  Prefix] 
[Argument  Prefix] 
[Argument  Prefix) 
[Argument  Prefix] 
[Argument  Prefix] 
[Argument  Prefix) 
[Argument  Prefix] 
[Argument  Prefix) 
[SKETCH  Attribute  Macro] 
[SKETCH  Attribute  Macro] 


(has-sizes  ’ar_array  [’at/x_lengtli]) 
(has-parent-sizes  *ar_array  [’at/xjength]) 
(has-desired-sizes  'ar_array  [’at/xjengthl) 
(has-origins  ’ar_array  j'at/x_lengLh]) 
(has-desired-origins  'ar_array  |’ar/x_lengthj) 
(has-steps  ’ar_array  [’at/x_lengLh]) 
(has-increments  ’ar_array  [■at/xjengtlij) 
(has-parent-increments  'ar_array  [’at./x_length]) 
(has-parent-offsets  ’ar_array  [’at/x_lengtli[) 
(has-offsets  ’ar_array  [’at/\_length)) 
(has-parent-scales  ’ar_array  [’at/xjength]) 
(has-scales  ’ar_array  [’at/\Jength]) 


[SKETCH  Attribute  Macro] 
[SKETCH  Attribute  Macro] 
[SKETCH  Attribute  Macro] 
[SKETCH  Attribute  Macro] 
[SKETCH  Attribute  Macro] 
[SKETCH  Attribute  Macro] 
[SKETCH  Attribute  Macroj 
[SKETCH  Attribute  Macroj 
[SKETCH  Attribute  Macro] 
[SKETCH  Attribute  Macro] 
[SKETCH  Attribute  Macro] 
[SKETCH  Attribute  Macro] 


(by-expression  'ar_array) 
(by-value  ’ar_array) 
(has-array-file  ’ar_array) 
(has-array-format  ’ar_array) 
(has-been-changed  ’ar_array) 
(is-readonly  ’ar_array) 

(is- immovable  ’ar_array) 

*  default-array-element-type* 
*default-array-long-exponent* 

*  default-array-short-exponent* 


[SKETCH  Attribute  Macro] 
[SKETCH  Attribute  Macro) 
[SKETCH  Attribute  Macro] 
[SKETCH  Attribute  Macro] 
[SKETCH  Attribute  Macro] 
[SKETCH  Attribute  Macro] 
[SKETCH  Attribute  Macro) 
[LISP  Global  Variable) 
[LISP  Global  Variable] 
[LISP  Global  Variable] 


OVERVIEW:  A  SKETCH  array  object  is  an  array  of  elements  which  are  numbers  or  other 
SKETCH  objects;  any  SKETCH  object  type  with  a  has-size  attribute  speci¬ 
fying  the  length  of  objects  of  that  type  in  bits  can  be  the  value  of  the  array 
has-  eleineiit-  type. 


A  numeric  element  type  can  be  either  fixed  point  or  floating  point.  For 
fixed  point  element  types  {a-ubit,  a-char,  a-uchar,  a-short,  a-xi$horf,  a-long, 
or  a-ulong),  the  array  has  a  has- exponent  attribute  such  that  actual  value  of 
an  element  equals  the  stored  value  times— 
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.'yhii- tip  Otic  til  ailribule 


A  SKETCH  array  object  actually  defines  two  arrays:  a  parent  array,  and  a 
slice  of  that  parent.  The  slice  is  a  part  of  the  parent  defined  by  giving  ori¬ 
gins  for  the  slice  in  the  parent,  sizes  for  the  slice,  and  multipliers  called 
steps  for  converting  slice  subscripts  into  parent  subscripts.  These  slice 
parameters  can  be  changed,  allowing  the  slice  to  move  around  inside  the 
parent.  The  parent  has  some  parameters  of  its  own:  sizes,  increments, 
offsets,  and  scales,  which  cannot  be  changed. 

SKETCH  arrays  have  exactly  G  dimensions,  named  X,  Y,  Z,  T,  U,  and  V,  in 
that  order.  Later  dimensions  may  have  their  size  set  to  1  if  they  are  not 
needed. 

SKETCH  arrays  have  two  modes:  allocated  nnd  unallocated.  In  allocated 
mode  memory  is  allocated  for  the  elements  of  the  array,  while  in  unallo¬ 
cated  mode  no  memory  is  allocated  for  the  elements,  .\rrays  are  initially 
unallocated,  and  become  allocated  only  when  their  elements  are  referenced. 
The  iillocatt-arniy  macro  checks  whether  an  array  is  allocated,  and  allocates 
it  elements  if  not.  The  call— 

[allocate- (iTTny  ar_array) 

returns  ar_array  as  its  value,  while  ensuring  that  the  elements  of  ar_array 
are  allocated. 

When  the  elements  of  an  array  are  allocated,  their  initial  values  may  be  pro¬ 
vided  by  the  has-array-file,  by-expression,  or  by-value  attributes  explained 
below. 

Most  computation  on  SKETCH  arrays  is  done  by  C  code.  The  call  to 
allocate-array  just  given  is  typically  used  as  an  argument  expression  to  a 
LISP  call  of  a  C  function,  in  order  to  ensure  that  the  array  passed  to  the  C 
function  is  allocated.  E.g.— 

(cc/iecA:  (_my_C_function  [allocate-array  my- array)  ...)) 

Array  elements  can  be  stored  in  MOS  memory,  or  in  files,  or  in  both  places. 
Arrays  which  are  stored  in  files  have  a  has- array- file  attribute,  and  an  asso¬ 
ciated  has-been-changed  attribute.  These  keep  track  of  where  the  array  is 
stored  in  the  file  system,  and  whether  the  in-MOS  version  still  matches  the 
in-file  version. 

THE  PARENT:  The  parent  array  is  described  by  its  sizes,  increments,  offsets,  and  scales. 

The  parent  array  subscript  for  a  given  dimension  may  range  from  0  to  the 
size  of  the  dimension  minus  1.  Each  time  the  subscript  is  incremented  by 
1,  the  address  of  the  element  referenced  is  incremented  by  the  size  of  the 
element  times  the  increment  of  the  dimension.  Thus  if  the  dimension 
increment  were  4,  each  unit  increment  in  the  subscript  would  increment 
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the  address  by  4  times  the  element  size. 

Parent  subscripts  may  be  mapped  onto  a  real  number  scale  which  is  used 
for  display  purposes.  Each  dimension  may  have  a  scale  and  an  offset. 
Subscript  I  is  mapped  onto  the  real  number— 

I  *  scale  -h  offset  +  0  5  *  scale, 

where  the  last  term  is  present  because  subscript  I  is  thought  of  as  denot¬ 
ing  the  interval— 

[1  -  0.5,  1  -h0  5) 

and  offset  corresponds  to  the  lower  bound  of  the  real  number  interval 
which  the  subscript  0  maps  onto. 

THE  SLICE:  The  slice  is  determilied  by  the  parent  and  by  the  following  parameters:  sizes, 
origins,  and  steps.  The  sizes  are  the  dimension  sizes  of  the  slice.  The  origins 
are  the  parent  array  subscripts  onto  which  the  slice  0  subscripts  map.  The 
steps  are  the  parent  array  subscript  changes  that  correspond  to  a  the  slice 
subscript  changes  of  +1.  Thus  for  each  dimension— 

parent-subscript  =  origin  +  step  *  slice-subscript 
0  <  slice-subscript  <  slice-size. 

It  is  possible  to  try  to  specify  a  slice  that  does  not  fit  inside  the  parent  array. 
If  this  happens,  the  actual  slice  sizes  and  origins  are  modified  until  the  slice 
does  fit  inside  the  parent,  or  if  this  is  impossible,  the  slice  sizes  are  all  set  to 
0.  Thus  the  slice  has  two  sets  of  sizes:  desired  sizes  and  actual  sizes,  and  two 
sets  of  origins:  desired  origins  and  actual  origins.  The  actual  sizes  and  ori¬ 
gins  are  computed  from  the  desired  sizes  and  origins,  plus  the  steps  and 
parent  parameters,  by  a  process  called  clipping. 

CLIPPING:  Clipping  reduces  the  actual  sizes  and  changes  the  actual  origins  of  the  slice  so 
that  it  will  fit  inside  the  parent  array 

One  form  of  clipping  changes  the  actual  slice  origins  until  they  are  legal 
parent  array  subscripts.  This  is  done  by  repetitively  adding  the  the 
dimension's  slice  step  to  the  actual  slice  origin  until  the  actual  origin  is  legal, 
and  reducing  the  actual  slice  size  by  1  for  each  step  added.  If  this  process  will 
not  work  (because  adding  the  step  would  move  the  origin  away  from  0 
instead  of  toward  0),  the  actual  size  will  be  made  0. 

The  other  form  of  clipping  merely  reduces  the  actual  slice  sizes  until  the  larg¬ 
est  slice  subscripts  map  onto  legal  parent  subscripts. 

If  any  actual  size  is  reduced  to  0  by  clipping,  then  all  the  actual  sizes  are 
forced  to  0. 

.\RGUMENT  PREFIXES:  Prefixes  such  as  ubar^  and  sar_  specify  that  the  argument  is  of 

an-array  type  and  has  a  particular  element  type,  according  to  the 
following  table— 
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Argument 

Prefix 

Element  Type 

ar_ 

— 

unspecified 

ubar_ 

a-  ubit 

l-bit  unsigned  integer. 

car_ 

a-char 

8-bit  signed  integer. 

ucar_ 

a-uchar 

8-bit  unsigned  integer. 

sar_ 

a-short 

16-bit  signed  integer. 

usar_ 

a-nshort 

16-bit  unsigned  integer. 

lar_ 

a-long 

32-bit  signed  integer. 

ular_ 

a-ulong 

32-bit  unsigned  integer. 

far_ 

a-Jioat 

32-bit  floating  point  number 

dar_ 

a-double 

64-bit  floating  point  number 

HAS-ELEMENT-TYPE:  The  type  of  the  elements  of  an  array.  A-type  object.  Possible 

values  include  a’long^  a-short,  and  a-char  for  signed  32.  16,  and  8 
bit  integers;  a-iilong,  a-usliorty  a*ucliar,  and  a-nbif  for  unsigned  32, 
16,  8,  and  1  bit  integers;  and  a-double  and  a-float  for  64  and  32  bit 
floating  point  numbers. 

Other  values  are  possible:  array  elements  may  be  C  met u res. 

The  default  element  type  for  array  creation  is  stored  in  the  global 
variable  ^defaull-array-etenierU-type*.  which  itself  defaults  to  a- 
long. 

Any  element  type  value  must  have  a  has-size  attribute  specifying 
the  length  of  the  array  element  in  bits  if  the  array  elements  are 
allocated.  For  example,  {lia$-$ize  a-long)  equals  32.  The  lias-size 
attribute  of  the  element  type  does  not  have  to  be  known  for  arrays 
whose  elements  are  never  allocated. 

HAS-EXPONENT:  A  fixnum:  block  floating  point  elements  of  ar_array  should  be  con¬ 
sidered  as  integers  which  are  multiplied  by  to  get  the  true 

numeric  value  of  the  element,  where  x_exponent  is  the  lias-cxponenf 
attribute  of  ar.array. 

If  ar^array’s  element  type  is  a-long,  the  has- exponent  attribute  defaults 
to  the  value  of  the  global  variable  *defautt-arr(iy-long-exponent*^  which 
itself  defaults  to  -16.  If  ar_array’s  element  type  is  a-sliorf,  the  lias- 
exponent  attribute  defaults  to  the  value  of  the  global  variable  *def(iult- 
array-short- exponent* ^  which  itself  defaults  to  -8.  Otherwise  the  has- 
exponent  attribute  defaults  to  0. 

The  lias-exponent  attribute  is  not  used  if  tlie  element  type  is  not  a-long, 
a-ulong^  a-short,  a-tishort^  a-cliar,  a-ticliar,  or  a-xibit. 

AT/X_LENGTH:  Many  array  attributes  are  lists  of  numbers,  one  for  each  dimension. 

Examples  are  lias-sizes^  lias-increments,  and  lias-origiifs.  When  one  of 


Printed  April  27,  1989 


ARRAYS 


7-7 


these  attributes  is  gotten,  a  list  of  6  numbers  is  normally  returned,  since 
that  is  the  normal  number  of  dimensions  of  an  array. 

If  the  at/x_length  parameter  is  given  as  a  positive  integer  while  getting 
one  of  these  attributes,  then  it  specifies  the  length  of  the  list  returned. 
The  numbers  added  to  the  end  of  the  list,  if  this  number  is  larger  than  6, 
depend  upon  the  particular  attribute:  e.g.,  has-sizes  adds  l^s,  has- 
increments  adds  the  minimum  number  of  elements  required,  to  hold  the 
array,  and  has-origins  adds  O's. 

If  the  at/x_length  parameter  is  given  the  value  do-shorten,  the  list  got¬ 
ten  is  shortened  by  omitting  from  its  end  any  numbers  equal  to  the 
number  that  would  be  added  to  the  end  of  the  list  if  it  were  to  be 
lengthened.  E.g.,  I’s  are  omitted  from  the  end  of  has-sizes,  and  O's  from 
the  end  of  has-origins. 

For  some  attributes,  like  has-offsets,  nil  may  be  an  element  of  the  attri¬ 
bute  value  list,  just  as  if  it  were  a  number.  For  these  attributes  nit  is 
the  element  added  to  lengthen  a  list,  or  the  element  removed  from  the 
end  to  shorten  the  list. 

R\S.SIZES: 

HAS-P.AJ^ENT-SIZES: 

HAS-DESIRED-SIZES:  The  list  of  the  integer  dimension  sizes  of  the  array.  There  are  three 
such  lists:  the  parent  sizes,  the  desired  slice  sizes,  and  the  actual 
slice  sizes.  If  the  slice  is  the  same  as  the  parent,  all  three  lists  are 
the  same,  and  may  be  denoted  by  the  has-sizes  attribute. 

The  parent  sizes  may  be  set  when  the  array  is  initialized,  but  not 
self.  The  desired  sizes  may  be  set/  at  any  time,  to  change  the 
definition  of  the  slice.  The  actual  sizes  are  computed  according  to 
the  rules  of  CLIPPING  above. 

Allowable  subscripts  for  a  given  dimension  range  from  0  through  the 
actual  dimension  size  minus  1. 

The  has-sizes  attribute  returns  the  actual  sizes  when  it  is  read. 
However,  it  sets  the  desired  sizes  when  it  is  self.  It  also  serves  as  the 
default  for  both  parent  and  desired  sizes  when  an  array  is  initialized. 

The  integer  sizes  must  be  non-negative.  If  any  are  0,  the  parent  or 
slice  is  empty.  Size  integer  lists  may  be  abbreviated  by  omitting  Ts 
at  the  end,  as  long  as  the  list  does  not  become  empty. 

When  the  lias-sizes,  lias-parent-sizes,  or  lias-desired-sizes  attributes 
are  read,  an  extra  at/xjength  argument  may  be  given  to  specify  the 
length  of  the  list  of  sizes  returned.  This  list  will  then  be  either  trun¬ 
cated,  filled  out  by  adding  Ts,  or  shortened  by  omitting  Ts  from  the 
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end. 

When  the  has-sizes  or  has’clesired-sizes  element  is  set/,  nil  may  be 
used  as  a  new  dimension  size  in  order  to  indicate  that  the 
corresponding  dimension  size  is  not  to  be  changed.  Also,  sizes  omit¬ 
ted  from  the  end  are  taken  to  be  7iit  in  this  sense,  and  are  not 
assumed  to  be  1.  For  example, 

{self  {lias-sizes  x  ^{nil  8))) 

will  change  only  the  2^nd  (Y)  dimension’s  desired  size. 

When  an-array  is  printed  or  unevaluated,  the  lias-parent-sizes  attri¬ 
bute  label  is  replaced  by  the  has-sizes  attribute  label  in  the  output. 
If  both  desired  and  parent  sizes  are  the  same,  only  one  sizes  attri¬ 
bute  is  output,  with  the  has-sizes  label. 

R\S-ORIGINS: 

R-VS-DESIRED-ORIGINS:  A  list  of  the  origins  of  the  current  ar_array  slice  within  its  parent 

array.  The  origins  are  the  parent  subscripts  to  which  the  slice  0 
subscripts  correspond.  Because  of  clipping,  there  are  two  sets  of 
origins:  the  desired  origins,  and  the  actual  origins.  The  desired 
origins  may  be  set/,  but  the  actual  origins  are  computed  accord¬ 
ing  to  the  rules  of  CLIPPING  above. 

An  origin  list  may  be  of  any  length  with  O’s  omitted  from  the 
end. 

The  has-origins  attribute  returns  the  actual  origins  when  it  is 
read,  but  sets  the  desired  origins  when  it  is  set/ or  used  as  an  ini¬ 
tial  value. 

When  the  has-origins  or  has- desired-origins  attributes  are  read, 
an  extra  at/xjength  argument  may  be  given  to  specify  the 
length  of  the  list  of  origins  returned.  This  list  will  then  be  either 
truncated,  filled  out  by  adding  O’s,  or  shortened  by  omitting  O’s 
from  the  end. 

A  value  being  self  to  the  desired  origins  may  have  a  nil  origin  for 
a  particular  dimension,  in  which  case  the  value  of  that 
dimension’s  desired  origin  will  not  be  changed.  Origins  omitted 
from  the  end  are  taken  to  be  nil  in  this  sense,  and  are  not 
assumed  to  be  0. 

When  an-array  is  printed  or  unevaluated,  the  has- desired- origins 
attribute  label  is  replaced  by  the  has-origins  attribute  label  in  the 
output. 

HAS-STEPS:  A  list  of  the  integer  steps  of  the  current  slice  within  the  parent  array.  For 
each  dimension,  the  step  is  the  increment  in  the  parent  array  subscript  that 
corresponds  to  a  unit  increment  in  the  slice  subscript.  A  step  may  be 
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negative  or  zero.  The  steps  may  be  set/. 

The  list  may  be  of  any  length  with  Ts  omitted  from  the  end. 

When  the  lias-steps  attribute  is  read,  an  extra  at/xjength  argument  may  be 
given  to  specify  the  length  of  the  list  of  steps  returned.  This  list  will  then  be 
either  truncated,  filled  out  by  adding  Ts,  or  shortened  by  omitting  Ts  from 
the  end. 

When  the  steps  are  setf^  the  new  value  may  have  a  nil  step  for  a  particular 
dimension,  in  which  case  the  value  of  that  dimension’s  step  will  not  be 
changed.  Steps  omitted  from  the  end  are  taken  to  be  nil  in  this  sense,  and 
are  not  assumed  to  be  1. 

HAS- INCREMENTS: 

R\S-PARENT- INCREMENTS:  A  list  of  the  integer  increments  for  the  array.  An  array  is 

mapped  onto  a  one  dimensional  vector  by  multiplying  each 
subscript  by  its  corresponding  increment,  summing  these 
products,  adding  a  vector  origin,  and  using  the  result  as  a 
vector  index.  The  vector  origin  specifies  the  array  element 
which  has  all  zero  subscripts,  and  the  index  is  measured  in 
units  one  array  element  long. 

Increments  are  therefore  measured  in  units  that  are  one 
array  element  long.  Thus  for  elements  of  type  a-ubtt,  incre¬ 
ments  are  measured  in  units  of  1  bit,  whereas  for  elements  of 
type  a-long^  increments  are  measured  in  units  of  32  bits. 

There  are  two  sets  of  increments.  The  parent  increments  are 
set  when  the  array  is  initialized,  and  cannot  be  self.  The 
slice  increments  always  equal  the  parent  increments  times 
the  steps,  for  each  dimension.  They  cannot  be  self,  but 
change  when  the  steps  change. 

A  list  of  increments  may  be  of  any  length.  A  value  omitted 
from  the  end  of  a  list  of  parent  increments  must  equal  the 
size  N,  in  units  of  one  array  element,  of  the  smallest  vector 
that  will  include  all  elements  with  the  subscripts  of  the  pre¬ 
vious  dimensions  ranging  over  their  entire  range,  according 
to  the  sizes  and  increments  of  these  previous  dimensions. 
Here  the  dimensions  are  those  of  the  parent  array,  and  not 
the  slice. 

The  has-increments  attribute  returns  the  slice  increments 
when  it  is  read,  but  sets  the  parent  increments  when  it  is 
used  as  an  initial  value.  Neither  kind  of  increments  can  be 
self. 

When  ^he  has-increjnents  or  has-pareni-increinents 
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a\S-OFFSETS: 

R4S-PARENT-0FFSETS: 


HAS-SCALES: 

HAS-PAKENT-SCALES: 


attributes  are  read,  an  extra  at/xjength  argument  may  be 
given  to  specify  the  length  of  the  list  of  increments  returned. 
If  N  is  as  above,  then  the  list  returned  will  be  either  trun¬ 
cated,  filled  out  by  adding  N*s,  or  shortened  by  omitting  N’s 
from  the  end. 

When  an-array  is  printed  or  unevaluated,  the  lias-pareJif- 
increments  attribute  label  is  replaced  by  the  has-increments 
attribute  label  in  the  output.  Slice  increments  are  never 
printed  and  never  appear  in  an  unevaluated  array. 


A  list  of  nzTs  or  flonum^s.  Each  Jionnm  is  the  value  that  >0.5  is 
mapped  onto  by  the  ruler  associated  with  the  corresponding 
dimension.  A  nil  indicates  there  is  no  ruler  for  the  dimension. 
Values  omitted  from  the  end  of  the  offsets  list  must  equal  nil. 

There  are  two  such  lists:  the  offsets  of  the  parent  array,  and 
those  of  the  slice.  The  latter  may  be  computed  from  the  parent 
offsets  and  scales,  and  the  slice  origins,  by  the  formula— 

slice-offset  =  parent-offset  -1-  parent-scale  *  actual-slice-origiii. 

\  slice  offset  is  7ii7  if  the  corresponding  parent  offset  or  scale  is 
nii 

The  haS’Offsets  attribute  returns  the  slice  offsets  when  it  is  read, 
but  sets  the  parent  offsets  when  it  is  used  as  an  initial  value  or 
self.  The  parent  offsets  can  be  self  only  when  their  previous 
value  is  nil.  Slice  offsets  cannot  be  initialized  or  setf. 

When  the  has- offsets  or  has-parent-offsets  attributes  are  read,  an 
extra  at/xjength  argument  may  be  given  to  specify  the  length  of 
the  list  of  offsets  returned.  This  list  will  then  be  either  trun¬ 
cated,  filled  out  by  adding  niTs,  or  shortened  by  omitting  nzTs 
from  the  end. 

When  an-array  is  printed  or  unevaluated,  the  has-parent-offsets 
attribute  label  is  replaced  by  the  has-offsets  attribute  label  in  the 
output. 


A  list  of  niPs  or  flonumPs.  Each  flonum  is  the  scale  of  the  ruler 
associated  with  the  corresponding  dimension.  The  scale  is  the 
increment  in  ruler  range  for  1  unit  increment  in  ruler  domain.  A 
nil  indicates  there  is  no  ruler  for  the  dimension.  Values  omitted 
from  the  end  of  the  offsets  list  must  equal  nil. 

There  are  two  such  lists:  the  scales  of  the  parent  array,  and  those 
of  the  slice.  The  latter  is  the  product  of  the  parent  scales  and  the 
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slice  steps. 

The  has-scates  attribute  returns  the  slice  scales  when  it  is  read, 
but  sets  the  parent  scales  when  it  is  used  as  an  initial  value  or  self. 
The  parent  scales  can  be  sefj  only  if  their  previous  value  is  nil 
The  slice  scales  cannot  be  self. 

When  the  luis’scales  or  has-parent’scales  attributes  are  read,  an 
extra  at/xjength  argument  may  be  given  to  specify  the  length  of 
the  list  of  scales  returned.  This  list  will  then  be  either  truncated, 
filled  out  by  adding  ruTs,  or  shortened  by  omitting  niPs  from  the 
end. 

When  an-array  is  printed  or  unevaluated,  the  has-parent’Scalcs 
attribute  label  is  replaced  by  the  lias-scales  attribute  label  in  the 
output. 

PROTOTYPES: 

DO*SR\RE-ELEMENTS:  Evaluating  an  expression  such  as— 

(an-arraij  ar_prototype  has- element- type  a-short  ...) 

will  make  a  copy  of  ar^prototype,  replacing  any  nr_prototype 
attributes  by  those  given  explicitly  in  the  expression. 
Ar_prototype  is  called  the  prototype. 

If  the  elements  of  ar_prototype  have  been  allocated,  then  the  ele¬ 
ments  of  the  result  will  be  allocated,  and  will  be  copies  of  the  ele¬ 
ments  of  ar_prototype.  In  this  case  the  parent  sizes  of  the  result 
must  equal  those  of  ar_prototype.  Because  array  elements  must 
be  copied,  only  numeric  type  elements  can  be  handled.  The 
result’s  has-exponent  will  be  computed  by  array-copy-exponent  if 
the  result  does  not  have  the  same  element  type  as  ar_prototype 
and  the  has-exponcnt  attribute  is  not  explicitly  given  a  numeric 
value  in  the  expression  above.  Array-copy-exponent  will  also  be 
used  if  the  has-exponent  attribute  is  explicitly  given  the  value  nil 
in  the  expression  above,  even  if  the  result  has  the  same  element 
type  as  ar_prototype. 

If  g-jshare-elements  is  present  and  non-nil,  the  elements  of 
ar_prototype  will  be  allocated  if  that  has  not  already  been  done, 
and  the  result  will  share  elements  with  ar_prototype.  In  this  case 
no  attempt  must  be  made  to  change  the  parent  size,  parent  incre¬ 
ments,  element  type,  or  exponent  of  the  prototype  while  making 
the  result. 

BY-EXPRESSION:  If  the  by-expression  attribute  value,  g_expression,  is  non-7u7,  it  will  be 
used  to  compute  an  initial  value  for  each  element  of  the  parent  array 
when  the  array’s  elements  are  allocated.  The  variables  .V,  T,  Z,  T,  U 
and  V  may  be  used  in  g^expression  as  the  parent  element  subscripts. 
No  other  variables  should  be  used  in  g^expr'ission  (variables  may  be 
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substituted  into  the  expression  when  the  expression  is  computed  by 
using  ‘  and  ,). 

The  by-txprtssion  attribute  of  an  array  is  set  to  nil  right  after  it  is  used 
to  initialize  the  array  elements. 

Currently  the  element  type  of  the  array  must  be  numeric  for  by¬ 
expression  to  work. 

Because  the  interpreter  is  used,  this  way  of  initializing  an  array  is  very 
slow  if  the  array  is  large. 

BY-VaLUE:  If  the  by-value  attribute  value,  g^value,  is  non-nil^  it  will  be  used  to  compute 
an  initial  value  for  each  element  of  the  parent  array,  when  the  array's  ele¬ 
ments  are  allocated.  G_value  is  a  list  of  sublists  of  sublists  ...  of  element 
values  that  are  used  to  initialize  the  elements.  The  innermost  lists 
correspond  to  the  first  (X)  dimension:  e.g.— 

(an-array  lias-sizes  '(2  3) 

by-value  ’((00  01)  (10  ll)  (20  21))) 

and— 

(an-array  has- sizes  (2  3) 

by-expression '{plus  X  [product  10  )*))) 

give  the  same  initial  elements. 

If  elements  or  sublists  are  omitted  from  the  end  of  a  list,  nil  values  will  be 
assumed. 

The  by-value  attribute  of  an  array  is  set  to  nil  right  after  it  is  used  to  initial¬ 
ize  the  array  elements. 

Currently  the  element  type  of  the  array  must  be  numeric  for  by-value  to 
work. 

Because  the  interpreter  is  used,  this  way  of  initializing  an  array  is  very  slow 
if  the  array  is  large. 

HAS- ARRAY-FILE: 

HASJJJIRAYJ'ORMAT: 

HAS-BEEN-CHANGED;  The  has- array- file  attribute  value  g_array-file  can  be  a  symbol— 

s_Rle-nanie 

equal  to  the  name  of  the  file  in  which  the  parent  array  is  stored,  or 
a  list  of  the  form— 

(s_file-name  x_offset) 

specifying  the  name  of  a  file  in  which  the  parent  array  is  stored 
beginning  at  the  given  offset,  or  a  list  of  the  form  — 
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IS-RE-'VDONLY: 


(s«volume-name  x_file- number  x^recorcl-number  x_offset) 

specifying  the  name  of  a  magnetic  tape  volume  containing  the 
parent  array,  the  file  number  of  the  file  on  the  tape  that  contains 
the  array,  the  record  number  of  the  record  in  the  file  that  contains 
the  array,  and  the  offset  of  the  parent  array  in  that  record. 


The  form  — 


s_file-name 


is  equivalent  to— 

(s_file-name  0). 

The  offset  specified  is  the  offset  of  the  first  byte  of  the  parent 
array,  which  need  not  be  the  first  byte  of  the  (0  0  0  00  0)  element 
if  the  parent  array  has  negative  increments. 


The  has-betn-changed  attribute  keeps  track  of  whether  the  MOS 
memory  and  file  system  versions  of  an  array  are  equal.  It  is  /  if 
array  elements  are  allocated  and  any  parent  element  has  been 
changed  since  the  array  was  last  written  to  or  read  from  its  has- 
array-file  attribute.  It  is  nil  otherwise. 


The  has-been-changed  attribute  can  be  self  to  /.  but  cannot  be  seif 
to  nil  or  initialized.  Any  non-7i//  value  is  equivalent  to  t.  Setting  it 
to  t  will  allocate  the  array  elements  if  that  has  not  already  been 
done. 


The  mechanism  for  keeping  track  of  changes  is  imprecise,  in  that 
whenever  two  arrays  share  elements,  setting  the  has-been-changed 
attribute  of  one  to  t  will  set  the  same  attribute  of  the  other  to  t. 
And  if  this  second  array  shares  an  element  with  a  third  array,  the 
third  array  will  also  have  its  has-been-changed  attribute  to  (,  even 
if  it  does  not  share  any  elements  with  the  first  array.  The  errors  in 
this  bookkeeping  will  always  set  has-been-changed  to  t  when  it 
should  be  left  nit.  It  will  never  be  set  nil  when  it  should  be  left  t. 


The  has- array- format  attribute  is  the  value  of  the  *computer- 
format*  global  variable  at  the  time  the  array  was  written  on  disk 
(it  is  nil  if  has- array- file  is  nil.  This  specifies  the  binary  format 
used  to  store  numbers  on  disk.  Sometimes  arrays  written  on  one 
computer  may  be  read  on  another  computer  with  different  number 
formats,  provided  an  appropriate  conversion  routine  is  provided 
(there  is  currently  no  mechanism  for  doing  this  implicitly). 

The  is-readonly  attribute  is  t  if  it  is  not  permissible  to  write  elements  of 

ar_array;  nil  if  it  is  permissible. 


Can  be  seif.  When  setf^  any  non- nil  value  is  equivalent  to  t. 
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Overlapping  arrays  may  still  be  writable  even  if  this  array  is  not.  in 
which  case  this  array^s  elements  might  still  get  changed  even  if  it  is 
readonly. 

IS-IMMOVABLE:  The  is-immovable  attribute  is  /  if  it  is  not  permissible  to  change  the 
ar_array  attributes  which  control  the  position  of  the  current  ar_array 
slice,  namely  the  has-dcsired-sizes^  ha$-dc$irtd-origins^  and  has-steps 
attributes;  nil  if  these  can  be  changed. 

Can  be  self.  When  self,  any  non-nil  value  is  equivalent  to  t. 

GARBAGE  COLLECTION:  Array  elements  (but  not  the  array  proper)  may  be  garbage  col¬ 
lected  if  the  array  is  not  stored  in  a  local  or  global  variable,  as  a 
function  argument  or  return  value,  or  as  an  element  of  a  list 
stored  in  one  of  these  placed  (but  not  as  an  element  of  a  siiblist 
of  a  list  stored  in  one  of  these  places). 

An  array  whose  elements  have  been  garbage  collected  in  this 
way  has  its  i$-collectcd  attribute  set  to  t.  Normal  array  func¬ 
tions  will  signal  an  error  if  passed  such  an  array.  . 

Thus  it  is  impossible  to  store  arrays  in  comple.x*  data  b;\scs, 
unless  these  arrays  are  bolted  down  by  storing  them  in  a  global 
variable,  or  as  an  element  of  a  list  stored  in  a  global  variable. 


The  purpose  of  this  form  of  element  garbage  collection  is  to 
allow  the  mark  and  sweep  algorithm  for  finding  unused  arrays 
to  run  much  faster  than  the  similar  algorithm  that  finds  unused 
objects.  This  permits  array  allocation  to  use  memory  at  a  fas¬ 
ter  rate  than  normal  object  allocation,  without  the  garbage  col¬ 
lector  becoming  a  major  drain  of  CPU  time. 


(an-array-summary  ha$-count  ’x_count  [SKETCH  Object] 

has-missing- count  *x_missing-count 
has-mtan  T_mean 

has- standard- deviation  ’f_standard-deviation 
has-maximum  ’f_maximum 
has-minimum  ’f^minimum 
has-sum  7_sum 

has- sum- squares  T_sum-squares) 


an-array-summary 

asum_ 

(has-count  ’asum_summary) 
(has-missing-count  *asum_summary) 
(has-mean  ’asum^ummary) 
(has-standard-deviation  ’asum_summary) 
(has-maximum  ’asum_summary) 
(has-minimum  ’asum_surhmary) 

(has-sum  *asum_summary) 
(has-sum-squares  ’asum_summary) 


[SKETCH  Type] 
[Argument  Prefix] 
[SKETCH  Attribute  Macro] 
[SKETCH  Attribute  Macro] 
[SKETCH  Attribute  Macro] 
[SKETCH  Attribute  Macro] 
[SKETCH  Attribute  Macro] 
[SKETCH  Attribute  Macro] 
[SKETCH  Attribute  Macro] 
[SKETCH  Attribute  Macro] 
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VALUE:  An  object  that  summarizes  the  elements  of  an  array.  In  the  various  summary 
statistics  missing  values  are  not  counted,  except  of  course  in  has-missing^coiint 
which  is  the  count  of  missing  values.  Has-count  is  the  count  of  non-missing 
values,  only.  Some  of  the  statistics  may  be  missing  [nil)  if  there  are  not  enough 
non-missing  values. 

.ar  [UNIX  File  Extension] 

FILE  FORM-A.T:  A  file  containing  array  elements:  e  g.  a  file  such  as  cache. ar  written  when 
uneval-object  is  called  by  u;ri/e-ca/a/o^  and  referenced  in  the  has-array-file 
attributes  of  an-array  objects. 

*  array- block-region-sizes  [LISP  Global  Variable] 

USER  ONLY  WHEN:  Having  problems  with  memory  overflow. 

USE:  * arr ay-block-region- sizes*  is  a  list  of  the  sizes  in  bytes  of  the  contiguous  regions 
that  will  be  allocated  to  hold  array  element  blocks. 

A  new  region  is  allocated  when  an  array  is  to  be  allocated  that  will  not  fit  into 
existing  regions.  Elements  of  the  *  array-block-region-sizes*  list  are  removed  until 
one  is  removed  that  is  larger  than  the  size  of  the  array.  All  the  removed  elements 
are  added  to  determine  the  size  of  the  new  region. 

If  the  array  is  too  large  for  this  to  work,  no  elements  of  the  list  are  removed,  and  a 
region  just  large  enough  for  the  array  is  allocated.  This  desparation  strategy  is 
likely  to  cause  later  problems. 

Setting  *  array-block-region-sizes*  to  a  list  whose  only  element  is  the  total  amount 
of  storage  available  for  arrays  is  the  best  way  to  avoid  running  out  of  space 
because,  it  avoids  array  storage  fragmentation.  However,  such  a  setting  will  lead 
to  a  substantial  delay  when  the  single  large  region  is  allocated. 

*array-blocks-history*  [LISP  Global  Variable] 

"“array-blocks-history-length*  [LISP  Global  Variable] 

VALUES:  *array-blocks-history*  is  a  history  of  the  time  spent  in  sweeping  and  compact¬ 
ing  array  blocks.  Its  length  is  limited  to  *array-blocks-history-length*  entries, 
and  the  latter  defaults  to  50. 
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{array-copy-exponent  ’ar_array  ’ty_element-type)  [LISP  Function] 

WHERE:  Ty_element-type  and  the  element  type  of  ar_array  are  both  numeric. 

RETURNS:  The  has-cxponcnt  value  most  appropriate  for  a  copy  of  ar^array  which  has 
element  type  ty_element-type. 

If  ty_ele men t- type  is  a-float,  a-double,  or  a^ubit,  the  exponent  is  0. 

If  ty_element-type  is  a-long  or  a-iilong,  the  elements  of  the  array  are  scaled  to 
fit  into  the  low  order  24  bits  of  the  32  bit  integers. 

If  ty_element-type  is  a-short^  a-ushort,  a-c/mr,  or  a-uc/mr,  the  elements  are 
scaled  to  use  all  available  precision  of  ty_element-type  without  any  clipping 
on  copying. 


If  ar^array  has  all  zero  or  missing  value  elements,  the  exponents  are  -16  for 
a-long  and  a-xdong,  -8  for  a-shori  and  a-short^  and  0  for  a-char  and  a-uchar. 


(bounds-of-array  ’ar_array  [n^factorj)  [LISP  Function] 

WHERE:  N_f actor  defau  Its  to  0.00001 . 


RETURNS: 


(njower-bound  n_upper-bound), 

where  n_lower-bound  is  the  minimum  of  all  the  elements  of  ar_array  minus 
epsilon,  and  n-upper-bound  is  the  maximum  of  all  the  elements  of  ar_array, 
plus  epsilon.  Epsilon  is  chosen  to  be— 

factor  *  ((maximum  of  all  array  elements)  -  (minimum  of  all  array  elements)) 

in  order  to  expand  the  interval  slightly.  If  epsilon  would  be  zero,  n_factor  is 
substituted  for  it.  If  epsilon  cannot  be  computed  because  the  array  has  no 
non-missing  elements, 

(-n_factor  n_factor) 


is  returned. 


(collect-array-blocks)  [LISP  Function] 

USE  ONLY  WHEN:  Playing  with  the  array  block  garbage  collector  (which  is  normally 
automatic). 

SIDE  EFFECT:  Calls  first  sweep-array-blocks  and  then  compact-array-blocks. 

RETURNS:  The  sum  of  the  number  of  fixnum’s  in  all  the  free  blocks. 
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(compact-array-blocks) 

*compact-array-blocks-count* 

*compact-array-blocks-time* 

*compact-array-blocks-bytcs* 

USE  ONLY  WHEN:  Playing  with  the  array 
automatic). 


[LISP  F unction] 
[LISP  Global  Variable] 
[LISP  Global  Variable] 
(LISP  Global  Variable] 

garbage  collector  (which  is  normally 


SIDE  EFFECT:  Compacts  all  the  blocks  in  the  array  block  allocation  area.  Does  not  mark 
the  free  blocks  first:  call  sweep-array-blocks  to  do  that. 


*compact-array-blocks’Coxint*  is  incremented  every  time  compact-array- 
blocks  is  called,  *compact-array-block$-liwt*  has  the  time  taken  by  the 
call  added  to  it,  and  *compact-array-blocks-bytes*  has  the  number  of  bytes 
moved  by  the  compactification  added  to  it.  All  these  variables  are  initial¬ 
ized  to  0.  The  time  is  measured  in  the  same  units  as  pthne:  see  *pltme- 
counts-per-second*. 

RETURNS:  The  sum  of  the  number  of  fixnum’s  in  all  the  free  blocks. 


(copy-array  'ar^oiitput  *ar_input)  [LISP  Function] 

WHERE:  .\r_output  and  ar_input  are  similar. 

RETURN:  Ar_output.  Copies  arjnput  elements  to  the  corresponding  ar_output  ele¬ 
ments.  Both  arrays  must  have  numeric  element  types,  but  these  and  the 
exponents  need  not  agree. 

BUG:  Currently  cannot  handle  non-numeric  element  types. 

(copy-of-array  ’ar_input)  [LISP  Function] 

RETURN:  A  new  array  which  is  a  copy  of  the  current  ar_input  slice  and  has  the  same  ele¬ 
ment  type,  exponent,  offsets,  scales,  and  parities  as  ar_input.  More  explicitly, 
the  parent  sizes,  offsets,  and  scales  of  the  result  equal  the  slice  sizes,  offsets, 
and  scales  of  ar_input. 

BUG:  Currently  cannot  handle  non-numeric  element  types. 

(duplicate-of-array  ’ar_array)  [LISP  Function] 

RETURNS:  A  new  array  which  shares  elements  with  ar_array,  and  has  the  exact  same 
standard  array  attributes,  except  for  the  is-immovablcj  has-array-filt^  by- 
expression^  and  by-value  attributes,  which  are  set  to  nil  in  the  result. 

The  elements  of  ar_array  are  allocated  if  this  has  not  already  been  done. 

Attributes  of  ar_array  which  are  not  documented  in  this  package  are  not 
copied  to  the  result. 
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(format-object  *ar_arra>’  ...)  JLISP  Function] 

EQUIVALENT  TO:  The  usual  fonnat-object,  except  that  ar_array’s  has-parent-sizeSj  has- 
parent-incrcmentSf  has- desired-sizes,  has- desired- origins,  has- steps, 
has-parent- offsets,  has- parent- sc  ales,  and  has-parities  values  are 
printed  with  some  editing.  The  ends  of  the  list  values  of  these  attri¬ 
butes  are  truncated  in  the  same  manner  as  the  do-sliorten  option  trun¬ 
cates  the  lists  when  they  are  gotten.  Also,  has-parent-sizes  is  renamed 
has-sizes,  has- parent- increments  is  renamed  lias-incremenfs,  has- 
parent-offsets  is  renamed  has-offsets,  and  lias-parenl-scales  is  renamed 
has-scales. 

(has-array-descriptor  ’ar_array)  [LISP  Macro] 

equivalent  TO: 

(allocate-array  ar_array) 

Has-array-descriptor  is  an  anachronism  and  will  be  removed  in  the 
future. 

(has-element  ’ar_array  ’x^ubscript  ...)  [SKETCH  .Attribute] 

(has-element  ‘ar_array  ’(x_subscript  ...))  SKETCH  .Attribute} 

WHERE:  The  element  type  of  ar_array  must  be  numeric,  or  an-lhif,  or  a  vector  type 
declared  by  declare- vector- type. 

These  latter  vector  elements  should  not  have  any  single  subelement  that  is 
stored  in  both  the  vector  and  hunk  part  (e.g.  in-hoth  subelements). 

VALUE:  The  element  of  the  current  ar_array  slice  corresponding  to  the  given  subscripts. 

A  numeric  value  may  be  nil  if  the  array  element  type  allows  signed  numbers. 

Numeric  values  will  be  fixnum  if  they  are  exact  integers  and  flonxim  otherwise. 

For  vector  values,  only  in-vector  subelements  are  remembered  in  the  array,  and 
all  tn-Aun/:  subelements  will  be  set  to  nil  in  the  element  value  read. 

Subscripts  range  from  0  to  1  less  than  the  size  of  the  corresponding  dimension. 
O^s  may  be  omitted  from  the  end  of  the  subscript  list. 

WHEN  SETF:  Numeric  values  will  be  automatically  converted  from  fixnum  to  flonu77\  and 
vice  versa  if  necessary. 

Non- nil  an-lbit  values  will  be  converted  to  t. 

Only  the  in-vector  subelements  of  a  vector  value  will  be  stored  in  the  array: 
the  zn-AunA  subelements  will  not  be  stored,  and  will  return  eVs  nil  when  the 
array  element  is  read. 

BUG:  If  for  a  vector  element  there  is  a  subelement  in  both  the  vector  and  hunk  part,  the 
value  returned  will  have  inconsistent  values  for  the  subeleinent  in  the  two  different 
places  it  is  stored,  unless  the  subelement  value  is  7iil. 
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(has-parent-ruler  ar^nrrnv  ‘x^dmien^iion )  'SKETCH  Attribute  Macroj 

(has-ruler  nr^ariny  x.dintensioii )  :SKETCH  Attribute  Macro 

\'.\LIT:  The  rulers  associated  uiili  ihe  .\_dmiension  dimension  of  ar.array.  These  are— 

’(.size  (.r'flsel  nil)  .scale), 

where  the  size,  ofiset,  and  scale  are  lor  either  the  parent  dimension  or  the  slice 
dnnonsion.  Thi^  ruler  nMp>  -0  o  oni"  the  ofiset  and  has  the  given  scale. 

Hoa-parcni-r filer  always  lel'ers  to  the  parent  dimension,  while  has-niler  refers  to 
the  slice  clinKuision  when  gotten,  and  the  parent  dimension  when  $etf 

Returns  nil  when  gotten  unless  both  offset  and  scale  are  non-niV. 

(inspect-array  'ai_array  [LISP  Function] 

’(i_size  ..  )  (i_oiigin  .  .)  ^’(i^^iep  -)!;!) 

SIDF  EITF.C'T  .•\pj)lie.''  sllce-of-arrai/  to  the  argument  list  and  prints  the  resulting  slice 
using  pnni-array  Then  echo>  the  current  slice  desired  origins,  and  wails 
foi  tin-  u.-ei  to  iy])e  a  command.  Typing  one  of  the  8  letters  surrounding 
5>*  on  the  standard  terminal  keyboard  moves  the  slice  in  the  corresponding 
direction:  leli.  right,  up.  down,  or  diagonal.  Here  a  lower  case  letter 
move"  by  Imll  the  size  of  the  slice  X  or  Y  dimension,  and  an  upper  case 
le;5er  moves  \)\  I  he  lull  size  of  the  dimension. 

Typing  a  set  of  integers  in  parentheses  sets  the  origins  to  the  values  indi¬ 
cated  (use  a  /?// value  for  no-change) 

Typing  a  conirol-D  or  $  exits  the  inspect-array  function. 

Except  for  the  control-D,  multiple  commands  may  be  typed  on  one  line,  in 
which  case  all  are  executed  first,  and  then  the  current  slice  is  printed  on 
the  console  terminal.  Just  typing  a  carriage  return  by  itself  reprints  the 
current  slice. 

(integerize-ruler  TuLruler)  [LISP  Function) 

WHERE:  RuLruler  is  a  possibly  unnormalized  ruler  that  can  be  normalized. 

RETURNS:  A  ruler  with  the  same  mapping  as  ruLruler,  but  with  a  possibly  different 
domain  w'hich  is  represented  by  a  single  non-negative  integer  N.  N  is  chosen 
to  be  the  largest  integer  such  that— 

(N-1.5  N-0.5) 

intersects  the  domain  of  ruLruler.  if  N  is  non-negative.  If  N  would  be  nega¬ 
tive,  N  is  chosen  to  be  0.  The  domain  of  the  ruler  returned  is— 

[-0.5  N-0.5). 

The  ruler  returned  is  normalized  except  for  its  domain  description,  which 
consists  of  just  the  integer  N,  rather  than  a  list  of  tw'o  bounds. 
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(log-bound-of-array  ar^array  ‘.\_sign  )  [LISP  Function’ 

RETURNS:  The  logarithm  base  2  ol*  the  smallest  power  of  2  such  that  all  non-missing  ele¬ 
ments  of  ar_arrav  have  an  •ab^olllte  value  less  than  that  power  of  2.  If  x_sign 
is  given  and  >  0,  all  negative  elements  will  be  treated  as  missing,  while  if 
N-sign  is  given  and  <  0.  all  positive  elements  will  be  treated  as  missing.  Zero 
elements  are  always  treated  as  missing.  If  all  the  elements  of  ar_array  are 
missing,  ml  is  returned. 

(look at- arrays  ['s.nanie  ...])  [LISP  Function] 

RETURNS:  A  list  of  pairs  (s.name  ar_valiie)  for  all  symbols  s_name  whose  value  is  an 
array. 

If  no  arguments  are  given,  the  arguments  are  taken  to  be  the  list  of  all  sym¬ 
bols  in  the  symbol  table. 

(map- by-ruler  'n_iuiinber  ’riiLrnler)  [LISP  Function] 

WHERE:  RuLruler  should  be  normalized.  No  checking  is  performed  for  invalid 
riiLruler's  (for  efficiency  rea.sons). 

RETURNS:  The  number  obtained  by  applying  the  affine  transformation  defined  by 
riiLruler  to  lunumber. 

(mirror-array  ’ar_ontput  'ar_inpiit)  [LISP  Function] 

WHERE:  There  is  a  list  of  integers  '(i.widtii  ...)  corresponding  to  dimensions  such  that 

the  size  of  ar_output  for  a  dimension  equals  the  size  of  arjnput  for  the  dimen¬ 
sion  plus  2  time.s  the  i_width  value  for  the  dimension.  Each  Lwidth  must  be 
non-negative,  but  may  be  zero 

RETURNS:  Ar^output  after  setting  its  elements. 

SIDE  EFFECT:  Ar_input  is  copied  into— 

[slice-of-array  ar^output 

[has-sizes  ar_input)  ’(Lwidth  ...)). 

The  rest  of  ar.output  is  filled  in  by  mirror  reflections  of  the  slice.  E.g., 
just  "above**  and  **belo\v"  the  slice  in  any  dimension  is  placed  a  copy  of  the 
slice  which  is  identical  to  the  slice  except  its  subscript  order  is  reversed  for 
the  given  dimension. 

NOTE:  The  element  types  of  ar_output  and  ar.input  may  differ,  as  long  as  both  are 
numeric. 

BUG:  Currently  each  Lwidth  may  not  exceed  the  size  of  the  corresponding  ar_input 
dimension. 

BUG:  Really  each  dimension  should  be  given  a  parity  which  determines  whether  the  ele¬ 
ments  with  subscript  0  or  size— 1  should  be  duplicated  or  not.  I.e.,  should  a  dupli¬ 
cate  of  the  top  row  be  placed  just  above  the  top  row,  or  should  a  duplicate  of  the 
second  row  down  be  placed  just  above  the  top  row,  leaving  the  top  row  undupli¬ 
cated.  Sometimes  the  answer  is  yes  and  sometimes  no,  depending  on  the  array, 
and  the  answer,  or  ‘dimension  parity’,  can  be  computed  automatically.  Currently 
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ilic  to))  row  olwny?  diiplicaied. 

(mirror-of-array  or_arri\\  '(i_wKhh  ...1)  [LlSf^  Function] 

RETURNS:  A  newly  crenied  array  each  of  whose  dimensions  is  larger  than  the 
corresponding  ar_array  dimension  by  2  times  the  corresponding  i_width.  The 
new  array  is  set  by  calling  the  mirror-array  function  with  it  as  the  output 
and  ar_anay  as  input. 

(move-array  ’ar_array  \\_diniension  \_change)  [LISP  Function] 

(move-array  ’ar_array  ’(N-('hange  [LISP  Function] 

RETURNS:  Ar_array  after  its  current  slice  is  modified. 

SIDE  EFFECT:  The  form  with  \_diniension  (see  X-dimti'ision)  changes  the  origin  of  the 
specified  dimension  by  the-  amount  .\_change  *  step,  where  step  is  the  slice 
step  parameter  for  the  dimension.  The  form  with  the  list  of  changes 
applies  these  changes  to  the  X,  Y,  Z,  T.  U.  and  dimensions  in  order, 

with  chnnge.s  not  given  or  being  given  as  nil  being  taken  a.s  0  (no  change). 

(normalize-ruler  ruLruler)  {LISP  Function] 

RETUR.NS:  RuLruler  alter  it  is  normalized.  .An  error  occurs  il*  ruLi  uler  cannot  be  nor¬ 
malized  or  doe>  not  liitvc  the  format  of  a  valid  ruler. 

(place-array  ’ar_array  ’x_dimension  A_size  [LISP  Function^ 

;‘x_origin  !‘.\_step  i) 

(place-array  'ar_array  ^(x^size  ...)  [LISP  Function] 

'■•(x.origiii  ...)  ;'(\_step 

WHERE:  Any  x_size‘s  must  be  non-negative,  but  x_origin’s  and  \_step’s  may  equal  any 
integer. 

RETURNS;  Ar_array  after  its  current  slice  is  modified. 

SIDE  EFFECT:  Modifies  the  current  slice  of  ar.array  by  setting  the  parameters  of  its 
dimensions  The  three  parameters,  x_size,  x_origin,  and  x_5tep,  refer  to 
the  desired  size  of  the  slice  dimension,  the  desired  value  of  the  parent 
array  subscript  corresponding  to  slice  subscript  0,  and  the  desired  incre¬ 
ment  in  the  parent  array  subscript  that  corresponds  to  a  unit  increment  of 
the  slice  subscript.  They  are  the  same  values  as  integers  listed  in  the 
array’s  has- dcsirtd- sizes ^  has- desired- origins^  and  has-sieps  attributes. 

The  form  with  x_dimension  given  (see  X-diinension)  sets  the  three  param¬ 
eters  for  the  specified  dimension. 

The  form  with  the  lists  of  x^ize’s,  x_origin’s,  and  x^step’s  sets  the 
parameters  for  all  dimensions  in  the  usual  order  X,  Y,  Z,  T,  U,  V. 

Omitted  parameters,  or  parameters  explicitly  given  the  value  nt7,  default 
to  the  current  slice  parameter  values:  i.e.  to  no  change  in  the  parameter. 
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(prepare-array  ‘ar_anny  ’(x_e.\pancl  ...)  jLlSP  Function] 

'ty_ek’nient-iy|H’  ;‘N_exponent  *  \viust-copy  ) 

*array-expander*  [LISP  Global  \‘ariable! 

RETURNS:  Eiihcr  ar_array,  or  a  new  array  which  is  a  copy  of  the  current  slice  of 
ar_array.  or  an  expanded  version  thereof.  The  array  returned  wdll  have  the 
given  element  type  and  exponent,  if  they  are  given  and  not  nil. 

If  ilie  '(x_expand  ...)  list  is  nil,  or  all  x^expand  values  are  0,  the  array 
returned  will  have  the  same  sizes  as  the  current  slice  of  ar.array.  In  this 
case,  if  ar_array  has  the  correct  element  type  and  exponent,  and  if  the  must- 
copy  sy>\ich  is  absent,  ar^array  itself  wdll  be  returned.  Otherwise  a  new  array 
will  be  returned  whose  elements  are  copies  of  those  of  ar_aiTay. 

If  x_expand  is  non- nil,  a  new*  array  is  created  whose  sizes  are  larger  than 
those  of  ar_arrny  by  the  values  in  the  ’(x_expand  ...)  list  rounded  up  to  the 
next  even  integers.  Then  the  call  — 

{fuvcall  *array-e2pa7}(ler*  ar_new*-array  ar^array) 

executed,  and  its  result  returned  as  the  value  of  prepare-array.  The  usual 
value  for  ^array-expander*  is  'mirror-array,  which  is  in  fact  the  default  value 
of  *  array- expander* 

The  above  call  to  *  array-expander*  will  be  made  if  the  element  type  or 
exponent  of  the  array  must  be  changed,  even  if  the  sizes  are  not  being 
changed. 

NOTE:  If  no  exponent  is  specified  wdien  changing  the  type  of  numeric  elements  to  a  block 
floating  point  type,  an  exponent  is  computed  automatically  using  array-edpy- 
exponent.  If  the  element  type  is  not  changed,  array- copy- exponent  wdll  not  be 
used. 

BUG:  Cannot  not  handle  non-numeric  array  element  types. 

(print- array  ar^array  [p_port  [xjength]])  [LISP  Function] 

WHERE:  The  element  type  of  ar_array  must  be  numeric  or  an-lbit. 

DEFAULTS:  P^port  defaults  to  poport  and  xjength  defaults  to  the  value  of  *line-length* 
(which  itself  defaults  to  80). 

SIDE  EFFECT:  The  array  is  printed  to  the  p«port.  A  line  length  of  xjength  columns  is 
assumed.  The  X  dimension  is  the  columns  dimension,  the  Y  dimension  is 
the  row^s  dimension. 

If  the  length  is  80  columns,  either  5,  10  or  80  columns  will  print  on  the 
first  line  of  a  row,  depending  on  the  array  element  type.  Excess  columns 
for  a  row^  are  printed  on  subsequent  lines  which  are  each  indented  by 
increasing  amounts. 

If  the  Z,  T,  U,  or  V  dimension  sizes  are  above  1,  then  multiple  two  dimen¬ 
sional  arrays  are  printed,  each  labeled  by  (*  *  Z  T  U  V). 
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Missing  values  are  printed  as  ml. 

BI  G:  The  oiili)ni  foi  mai  not  LISP  readable  and  leaves  something  to  be  desired  when  a 
row  spills  onto  more  than  one  line.  It  will  probably  be  changed  in  the  future. 

(read-array-elements  ‘ar^array  ‘g_ari*ay-file)  (LISP  Function] 

RETURNS:  Ai_array  after  its  elements  have  been  modified. 

SIDE  EFFECT:  Reads  from  the  file  location  specified  by  g_array-file  into  the  parent  array 
of  ar_array.  Sets  the  hai>- array- file  attribute  of  ar_array  to  g_array-file. 
Set.<^  the  has-beeu-changed  attribute  to  rul. 

See  H.\S-ARRA’^*-F1LE  under  an-array  for  the  layout  of  g_array-file. 

(reorganization-of-array  *ar_array  ’(\_Norigin  ...)  [LISP  Function] 

‘(\_xsize  ...)  ;‘(n— vincrement  ...)j) 

USE  O.N'LY  WHEN:  A  crazy  array  reorganization  is  required. 

WHERE:  I’nspecilied  origins  default  to  0.  iinspecitied  sizes  default  to  1,  and  unspecified 
increments  are  computed  in  the  same  manner  that  they  are  computed  when  a 
new  array  recreated  by  un-array 

RETURNS:  A  new  array  thra  shares  elements  with  ar_array.  The  parent  sizes  of  the  new 
array  arc  x_\size  .  ..  and  the  parent  increments  are  x_xincrement.  The 
parent  origin  element  of  the  new  array  is  the  element,  of  ar_array  designated 
by  the  subscripts  x_\origin  ...  . 

The  current  slice  of  the  new  array  equals  the  new  array’s  parent. 

WARNING:  If  one  is  not  careful,  some  elements  of  the  new'  array  may  not  be  elements  of 
ar_array.  However,  they  will  be  elements  of  some  ancestor  of  ar_array  (a 
parent  of  ar^array,  or  of  an  array  from  which  ar_array  was  made  by  slice- 
of-array.  or  something  like  that). 

It  is  an  error  if  there  is  no  ancestor  in  which  the  new  array  will  fit. 

(reset-array  ’ar_array)  [LISP  Function] 

RETURNS:  Ar^array  after  it  is  modified.. 

SIDE  EFFECT:  Resets  the  array  slice  s6  that  it  equals  the  parent. 
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(restrict-array  ’oi_anny  [LISP  Function] 

'\_sizc  ’.\_ongiii  *N_sicp’  ) 

RETURNS:  Ai^array  after  it>  ciirrcni  >li(e  modified. 

EQl*]\‘.\LENT  T<):  (plnce-arr<tj/  ai_;irray  D  x_size  x.origin  x^tep)  for  all  D  >  = 
x_diinension. 

(reverse-array  *ar_arniy  ’x«(linu-n>ion  I  [LISP  Function; 

RETURNS:  Ar_array  afier  ii.^  current  slice  is  modified. 

SIDE  EFFECT:  Reverses  the  order  of  .suUscripts  in  the  dimension  specified  by  x.dimension 
within  the  ciirreni  ai^array  slice  by  negating  the  dimension’s  step  and 
changing  the  (lim<Mi>ioir>  desired  origin  appropriately  to¬ 
ok!  (le'^ired  origin  -f  (desired  size  -  l)  *  (old  step). 

(round-ruler  ’ruLruler  ’lij'ueioi  ’Lpattern  )  [LISP  Function] 

WHERE:  NJactor  >  0 

RETURNS:  A  ruler  made  by  from  ruLruler  by  the  following  alterations.  First.  ruLruler 
is  noniKilizcd.  Secoiid.  the  ruler  ^cale  is  rounded  away  from  zero  until  it  is  an 
exact  multiple  of  nj'uetor.  Third,  the  ruler  is  matched  against  Lpattern.  and 
any  bound  that  matche>  a  nil  in  Lpattern  is  changed  to  nil.  There  should  be 
only  one  such  bound  and  (  hanging  it  to  nil  will  provide  the  freedom  neces¬ 
sary  to  recompute  it  and  make  the  ruler  valid. 

The  resulting  ruler  is  unnorinalized,  since  it  has  a  nil  bound. 

L.pattern  defaults  to  ((/  /)  (/  mV)),  which  allows  the  second  range  bound  to 
change. 

‘‘ruler”  [SKETCH  Term] 

“normalized  ruler”(SKETCH  Term] 

ruL  [Argument  Prefix] 

NORMALIZED  RULERS:  A  normalized  ruler  is  basically  a  list  in  the  format— 

((Ldomain-bound-1  Ldomain- bound-2) 

(Lrange-bound-1  Lrange-bound-2) 
f_scale), 

where  all  the  numbers  are  floating  point.  This  list  specifies  an 
affine  map  from  the  oriented  real  interval— 

[Ldomain-bound-1  Ldomain-bound-2) 
to  the  oriented  real  interval— 

[Lrange-bound-1  Lrange-bound-2). 

Note  that  these  intervals  may  have  their  bounds  switched:  that 
is— 

Ldomain-bound-1  >  Ldomain-bound-2 

or— 
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l_range-bouncl-l  >  r_range-bound-2 

are  allowed  In  aiiv  case,  the  map  sends  f_doinain-bound’l  onto 
l-range-boiind-l .  and  f_domain-bonnd-2  onto  f_range-boiind-2. 

F^cale  is  the  multiplier  used  in  the  ruler  affine  map.  A  ruler  is 
invalid  unless— 

(Lrange-bound-2  -  Lrange-bound-1 )  == 

f^scale  *  (f_domain-bound-2  -  f_domain-bound-l ). 

INTEGER  P.-VR.AAIETER.S.  If  any  of  the  five  parameters  in  a  ruler  are  integers,  the  ruler  is 

considered  to  be  unnormalized.  It  may  be  normalized  in  this 
case  simply  by  replacing  the  integers  by  their  floating  point 
equivalents. 

COXMiRSlOX  TO  DISC  RETE  BINS:  To  convert  the  real  line  to  discrete  bins,  we  assign  each 

real  number  to  the  nearest  integer:  we  roiivd  As  a 
consequence,  each  integer  can  be  thought  of  as  the  mid¬ 
point  of  an  interval  of  length  1.0.  If  the  integers  from 
0  through  N-1  are  to  represent  N  bins  covering  the  real 
interval  !L  I  I.  the  ruler  that  should  be  used  to 
represent  this  fact  is— 

((-0.5  .\-0.5)  (L  U)). 

.*\  real  interval  in  a  ruler  can  be  replaced  by  a  single 
integer  N.  This  integer  stands  for  the  interval  — 

(-0.5  N-0.5). 

Such  a  ruler  is  an  unnormalized  ruler,  and  can  be  nor¬ 
malized  by  replacing  the  integer  by  the  interval  it 
represents. 

PARTIAL  RULERS:  If  any  one  of  the  five  parameters  of  a  ruler  is  omitted,  it  can  be  com¬ 
puted  from  the  others.  Rulers  are  permitted  with  nil  as  one  of  the 
parameter  values.  These  are  unnormalized  rulers  that  may  be  nor¬ 
malized  by  replacing  the  ni7  with  a  computed  value. 

An  exception  is  made  if  f_scale  is  nil  and  f_domain-bound-l  = 
f.domain-bound-2,  in  which  case  the  ruler  cannot  be  normalized,  and 
is  considered  invalid. 

It  is  also  possible  to  specify  a  domain  or  range  by  a  nil  list,  which  will 
be  replaced  by  (-0.5  nil).  This  is  similar  to  having  an  integer 
specification  of  the  domain  or  range,  and  not  knowing  the  value  of  the 
integer. 

SCALE  FACTORS:  If  a  ruler  lias  a  list  (n_factor  [Lpattern])  in  place  of  f_$cale,  then  the 
ruler  is  unnormalized.  To  normalize  the  ruler,  it  is  treated  as  a  partial 
ruler  with  missing  scale,  the  scale  is  computed,  and  the  function  call— 

{rotmd-ruler  the-ruler  n_f actor  [Lpattern]) 
is  called  to  compute  a  ruler  which  is  then  normalized  and  returned. 
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sar_array 

|CType| 

ar_ 

I'Argument  Prefixj 

SAR.ARRAY 

jC  Global  Constant' 

ar_array— >sar_type 

[C  Macro] 

•ar.array— >sar_etype 

(C  Macro] 

a  r_a  rray — >  sar_esize 

(C  Macro] 

a  1  _a  r  I  n  y — >  sar_ex  p  o  n  e  n  t 

[C  Macro] 

a  r  r  ay — >  s  ar_u  b  b  ase 

[C  Macro] 

nr_array— >sar_cbase 

[C  Macro] 

ai_array— >sar_ucbase 

[C  Macro] 

ar_array— >sar_sbase 

[C  Macro) 

a  r_a  r  r  a  y — >  sar_u  sb  ase 

[C  Macro] 

a  r_a  r  r  a  y — >  sar_I  base 

[C  Macro] 

ar_arrny— >sar_ulbase 

[C  Macro] 

a  r_a  r  r  ay  —  >  sar_fbase 

[C  Macro] 

ar_array— >  sar_dbase 

[C  Macro] 

a  r_a  r  ray  —  >  sar_u  base 

[C  Macro] 

a  r  _a  r  r  a  \  —  >  s  a  r_i  b  as  e 

[C  Macro] 

ar_a!  ray— >  sar_edimensions 

[C  Macro] 

a  r_ai  ray  — >sar_cdimensions 

[C  Macro; 

n!_ari ay  — >sar_dimensions  -f  n 

[C  Macro’ 

a  r_a  nn  y  —  >  sar_xsi  ze 

1C  Macro! 

a  r_a  rray — >  sar_xin  cremen  t 

[C  Macro] 

a  r_a  rray — >  sar_y  si  ze 

[C  Macro] 

a  r_a  rray— >sar_y  increment 

(C  Macro] 
(C  Macro] 

ar_array— >sar_zsize 

ar^array— >sar_zincrement 

[C  Macro] 

ar_array— >sar_tsize 

[C  Macro] 

ar^array— >sar_tincrement 

[C  Macro] 

ar_array— >sar_usize 

(C  Macro] 

ar^array— >  sar_u  in  cremen  t 

[C  Macro] 

ar_array— >sar_vsize 

[C  Macro] 

ar_array— >8ar_vincrement 

USE:  An  snr^array  value  is  a  pointer  at  on-array  object. 

(C  Macro] 

SAR^RRAY equals  the  LISP  value  an-array,  and  is  the  value  of  the  sarjlypt  ele¬ 
ment  of  an-array  object. 

In  the  description  that  follows  we  assume  the  elements  of  the  array  are  allocated, 
as  this  is  nearly  always  the  case  with  C  code.  See  UNALLOCATED  ARRAYS 
below. 

ARGUKiENT  PREFIX:  The  ar_  prefix  denotes  C  arguments  of  sar^array  type. 

S.AR.T'^TE:  Ar_array—> sar_/ypc  equals  SAR^RRA  T,  and  is  an  sob^typc  value.  It  may 
be  used  to  verify  that  ar_array  points  at  an  array  descriptor. 

S.\R_ET\TE:  Ar_array— >sar_c/ypc  is  the  has- element- type  attribute  of  ar_array.  It  is 
an  sob^type  value. 
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S/UI^ESIZE:  .Ar^nnnv—  is  '^ize  in  bits  of  an  element  of  ar.array.  It  is  an  iut 

value  and  ec|U;ils  (iob^fsizf  (nr^array— >5ar_e/ype),  which  is  the  same  as  ilie 
attribuie  of  the  ha.'s^elewevl-fype  of  the  array.  Redundant,  but  use- 
ful  lor  speed. 

S.aP.EXPONENT:  Ar.arrny  — >snr.ex/^one7?/  is  the  /las-ejponcnf  attribute  of  ar_array.  It 
is  an  ivf  value  used  for  a  block  floating  point  array.  It  should  equal  0 
for  oilier  kinds  of  arrays. 

S.AB.UBBASE: 

S.AP.CBASE- 

S.\K_UCBASE: 

S.^K.SB.ASE: 

S.AR.USBASE: 

S.AR.LD.VSE 

S.AE.ULBASE: 

S.AR.FBASE: 

S.AP^DBASE: 

S.AR.UBASE: 

S.AP_1BaSE:  Ar_arrav  — >.S(;/_..6o>e  i>  the  base  address  of  the  array  elements:  that  is.  tin* 
addles-^  ol  the  element  with  subscripts  (0  0  0  0  0  0).  The  data  type  of  thi> 
addre.ss  is  given  according  to  the  following  table— 


sar^ubbase 

unsigned 

sar cbase 

char  * 

sar ucbase 

uchar  * 

sar^sbase 

short  * 

sar.usbase 

ushort  * 

sar.lbase 

long  * 

sar.ulbase 

ulong  * 

sar.ibase 

ini  * 

sar^ubase 

unsigned  * 

sar^fbase 

float  * 

sar.dbase 

double  * 

The  various  different  versions  of  this  structure  element  are  used  for  the 
different  types  of  array  element:  e.g.  sar^lbase  is  used  if  the  array  elements 
are  loughs. 

The  sar^xtbbasc  value  is  exceptional  in  that  it  is  a  bit  address  for  arrays  of 
unsigned  bit  elements  (all  other  addresses  are  byte  addresses).  When  right 
shifted  by  3  it  addresses  a  byte.  Its  low  order  three  bits  address  a  bit  within 
the  byte,  with  the  high  order  bit  being  at  address  0  and  the  low  order  bit  at 
address  7.  This  addressing  system  is  compatible  with  most  raster 
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input  'output  devices 

The  ^ar^cbaiie  value  may  be  cast  to  any  normal  C  pointer  lype  in  order  to 
get  a  pointer  at  the  elements  of  the  array.  The  only  exception  is  for  arrays 
of  unsigned  bits,  as  noted  above. 


The  convention  is  that  bit  addressing  (siir^ubbase)  is  used  if— 

(ar_nrray—> 5nr_e5ize  S:  07)  !=  0 

and  byte  addressing  (6(/r_r/n/5e,  ...)  is  used  otherwise.  I.e.,  byte  addressing  is 
used  if  the  element  size  is  a  multiple  of  one  byte. 

S.\R_EDIMENSIONS:  Ar_array— >  is  the  number  of  dimensions  of 


a!_array  with  0  size  after  clipping.  If  non-zero,  it  indicates  that  the 
array  is  empty.  Note,  it  is  not  the  same  thing  as  the  number  of  0 
dimension  sor^size  values,  as  all  the  later  are  zeroed  if  any  of  them 
are  zero. 


SAE.CDIMENSIONS  .\r_array — > 6Y/r_rr/n/?e«s/07/6  is  the  number  of  dimensions  of 


nr_aiTay  which  have  been  clipped,  in  the  sense  that  their  desired  size 
docs  not  etjual  their  actual  size. 


S.AR.DIME.NSIONS:  .Ar_nrray— > -f  n  is  a  pointer  to  the  array  dimension 


descriptor  for  the  n'tli  dimension  of  the  array.  The  standard  values 
of  n  ai  e  SAH^W  SAR_)\  SAR_Z,  SAR^T,  SAR^il,  and  5.4/?_V. 


S.4R_XSIZE  S.4R_XINCREMENT: 

SAR.YSIZE  S.4R_YINCREMENT: 

SAR_ZSIZE  S.^R.ZINCREMENT; 

SAR.TSIZE  SAR.ThNCREMENT: 

SAR.USIZE  SAR.UINCREMENT: 

SAR^VSIZE  SAR.VINCREMENT:  Ar^array— > 5ar_x5i2e  is  equivalent  to— 


(ar_array— >5ar_dimen5ion5  -f  SAR^X)  — >  sar^size 
and  ar_array—> 5ar_zmcremcn/  is  equivalent  to— 
(ar^array— >sar_rfimen5ions  +  SAR^JC)  — >  sardine rcmcnt. 
Similarlv  for  the  other  dimensions. 


UNALLOCATED  ARRAYS:  Arrays  whose  elements  are  not  allocated  appear  to  be  very 


much  like  allocated  arrays.  However,  their  sar^.^.basc  value  is 
set  to  point  to  a  region  of  virtual  memory  that  is  unimple¬ 
mented,  in  order  to  catch  reference  errors.  Also,  their  sar^csizc 
element  may  be  0  (to  allow  for  cataloged  arrays  whose  element 
types  are  unknown  to  the  current  program  and  which  will  never 
be  allocated  by  the  current  program). 
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sar_dimension 

adim_ 

;ulim_(liniension  — >sar_size 
adini^clirncnsion— >sar_increment 


[C  Type) 


[Argument  Prefix] 


|C  Macro] 
[C  Macro] 


USE  An  i$or_dvnevsiov  value  is  a  pointer  at  an  array  dimension  description  structure. 
There  is  one  such  structure  inside  av-arroy  ol)ject  for  each  of  the  array’s 
SA  R^iDIA  lENSl  0  A’5  dimensions. 

.\EGUMEXT  PREFIX:  The  odiiv^  prefix  denotes  C  arguments  of  sar_dw]cv.^ion  type 
S.APi.SlZE:  Adini_dimension  — >sr/r_.s?re  is  the  actual  size  of  the  array  dimension  (as  got¬ 


ten  by  the  has~sizcs  attribute  of  a7j-array  object).  It  is  an  int  value. 

The  dimension  s  subscripts  are  allowed  to  range  from  0  through  sor_si>e-l. 
This  size  ecjuals  the  desired  size  if  the  dimension  is  not  clipped,  but  will  be  less 
than  the  desired  size  if  the  dimension  is  clipped. 

If  the  array  is  empty,  this  value  will  be  zero,  even  if  this  dimension  is  not 
empty.  In  other  words,  if  any  dimensioivs  is  zero,  all  the  other 

dimensions’  f^ar^fiize’s  will  be  set  to  zero. 


S.AJ^.INCREMENT:  .\dim_dimension— > 6ur_7‘/;rre/»en/  is  number  of  array  elements  that 


must  be  skipped  in  memory  for  each  -fl  change  in  the  dimension's 
subscript.  Note  that  this  number,  which  is  an  is  in  units  of  array 
elements,  and  not  bytes  or  bits.  May  be  positive,  negative,  or  zero 

It  is  the  same  increment  as  gotten  by  the  lio$-tncremcnf$  attribute  of 
an-array  object. 


[C  Macro  Constant] 


SAR31DIMENSIONS 


VALUE:  The  maximum  number  of  dimensions  allowed  in  an  array.  Usual  value  is  6. 


[C  Macro  Constant] 


SAR31SIZE 


VALUE:  The  maximum  sar^size  of  an  individual  dimension.  Not  commonly  used,  and 


should  not  be  used  to  unnecessarily  restrict  software.  Sometimes,  however,  it  is 
convenient  to  allocate  one  dimension’s  worth  of  work  area  in  the  stack,  and  this 
constant  is  for  such  purposes.  The  usual  value  is  8192. 


Printed  April  27,  1989 


ARRAYS 


7-30 


sar^place  (nr_arra> .  .\_(linieni>ion.  [C  Function] 

x_^5lzc.  \_origin.  N«strp) 

SIDE  EFFECT:  Sei'^  the  (leaned  size,  desired  origin,  and  step  of  the  given  dimension 
(SAR^X.  SAR^)'.  ...)  of  nr^array.  Errors  are  indicated  by  a  call  to 
dfe^error  followed  by  a  return.  The  error  switch  should  be  checked  for  by 
the  caller. 

sar_similar  (ar.arriivl .  ar_nrrny2)  [C  MacroJ 

sar_xsimilar  (ar^arrayl.  ar_array2.  x.exclude)  [C  Function- 

RETURNS:  SAT^YES'I)  if  nr^arrnyl  and  ar_array2  are  both  sar^orrai/ objects  (they  ha\  e 
the  right  ^or_typc  element  value)  and  these  two  arrays  have  identical  dimen¬ 
sion  for  non-excluded  dimensions.  Otherwise  returns  SAT_NO{). 

Sar^simllar  excludes  no  dimensions,  while  sar^x^imilar  excludes  those  dimen¬ 
sions  D  (D  =  0.  1 .  ...)  for  which  the  bit  1  <  <D  is  on  in  x.exclude. 

sar_write  (ar^arrny  1  [C  Macro] 

RETURNS:  SAT_)r>  (I  if  ar_nrray  is  writable  {is-readoviy  attribute  is  vil),  and 
SA  7LAO  I i  it  ar_a!  ray  is  readonly. 

SIDE  EFFECT:  .Sei.'^  the  ha.*>-hecti-cltanti€(l  attribute  of  ar_array  to  t  if  the  array  is  writ¬ 
able.  Tlii-^  i.s  very  important  in  that  it  permits  the  array  disk  cacheing  to 
work  correctly. 

NOTE:  This  macro  should  be  used  on  every  array  that  is  to  be  w'ritten  by  a  C  function. 
The  result  returned  by  this  macro  should  be  checked  by  sfe^asseri. 

[C  Macro  Constant] 
[C  Macro  Constant] 
jC  Macro  Constant] 
[C  Macro  Constant] 
[C  Macro  Constant] 
[C  Macro  Constant] 

first  6  dimensions  of  an 
as  G  dimensional  arrays 


SARJJC 

SAR_Y 

SAR_Z 

SAR_T 

SAR_U 

SAR^V 

VALUE:  The  values  0  {SAR^^  through  5  (5A/?_V')  denoting  the 
array.  Arrays  with  fewer  than  6  dimensions  are  treated 
whose  later  dimensions  (closer  to  SAR^\^  have  size  1. 
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{sar_xfor_elements  (ar_arr:iv.  type,  base)  { 


\  I 
I  I 


{sar_xfor_2_elements  ra\  1 .  tvpcl.  baM-l, 

i'ir_nrrny2,  type2.  base2)  { 


u 

J  i 


{sar_xfor_3_elements  (ai^array  1 .  typel  base!. 

;\!_array2.  type2,  base2j 
ar_array3,  type3.  base3)  { 


f  I 


{sar_>cfor_4_elements  (nr^array  1 ,  lyprl.  basel, 

ar_array2,  type2.  base2, 
ni_airay3,  type3,  base3, 
ai_array*4,  type4,  base4)  { 


i  i 


{sar_for_elements  (ai_airay,  type)  \ 


u 

I  j 


{sar_for_2_elements  (ai^nirayl,  ai_aMay2,  type)  { 


u 

f  i 


{sar_for_3_ele merits  I ni^nrray  1 ,  ar_ai  ray2,  ar_array3, 

^ype)  { 


{sar_for_4_elements  (ar_nrrayL  ai_aira\‘2.  ar_array3, 

ar_array4,  type)  { 


X 

Y 
Z 
T 
U 

V 
xp 


I } 


[C  Macro: 
(C  Macro 


[C  Macro] 


[C  Macro^ 


[C  Macro] 
[C  Macro 
%  jC  Macro' 


[C  Macro 


(C  Local  Variable] 
(C  Local  Variable] 
(C  Local  Variable] 
(C  Local  Variable] 
(C  Local  Variable] 
[C  Local  Variable] 
[C  Local  Variable] 


SIDE  EFFECT:  Sar^jjor^clcmcnts  creates  a  loop  which  executes  the  body  ...  once  for  each 
element  of  ar_array.  This  macro  is  equivalent  to— 
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register  type  rp.  reiji^ltr  /tit  X: 
reg/i^ter  type  ///»:  register  mt  V: 
register  type  zp:  register  int  Z: 
register  type  tp:  register  iiit  T: 
register  type  t/p.  reg/ster  tut  U; 
register  type  vp.  register  iiit  T; 
if  {:iT_^vvziy—>  sar_e(li7iieii$io7is  ==  0) 
for  ( r  =  0.  vp  =  (type)  (base): 

y  <  (ar_array)—>  5ar_r5fre: 

-f-f  y  rp +=  (ar_array)— >6flr_in‘ricrcT7zc«/) 
for  {U  =  0.  vp  =  vp: 

r<  (ar_array)— >6flr_T/5T.:e; 

L.  up  +=  (ar_array)— >  677r_T/TTJCrcT?zc7i/) 
for  (r  =  0.  ///  =  up:  ^ 

T  <  ( nr_array  )— >  5r/r_/67re: 

-f-i-  T.  fp -f=  (ar_array)— >5nr_/inrrcmc7z/) 
for  (Z  =  0.  r/)  =  tp: 

Z  <  (ar_array)— >  6«r_c6'zre; 

-i— r  Z.  zp  -f=  (ar^array)— >6r7r_r?ncreT?iCT?/) 
for[y  =  0.  gp  =  zp. 

V  <  (ar_array )— >5ar_?/57ze: 

-f-}-  )  .  yp  -f=  (ar_array)— >6flr_j/Twcrcme7i/) 
for  {X  =  0,  xp  =  yp. 

X  <  (ar_array)— >5ar_r57>c: 

++  A’  xp  -{-=  (ar_array)—>5ar_Tincrc7nc7j/) 

Notice  that  the  macro  begins  with  declarations,  and  that  more  declara¬ 
tions  may  immediately  precede  the  macro.  The  pointer  xp  tracks  through 
the  elements  of  ar_array,  and  may  be  use  in  the  array  body  to  access  the 
current  element.  The  type  of  this  pointer  is  the  type  argument  to  the 
macro.  The  address  of  the  (0  00  0  00)  element  is  the  base  argument  to 
the  macro.  The  variables  X,  Y,  Z,  T,  U,  and  V  are  the  subscripts  of  the 
current  element. 

The  macros  sar_xfor^S_elementSf  sar^xfor_S^elements  and 
sar^for^4_elemeni$  are  similar  except  that  there  are  a  separate  set  of 
pointers  xip,  x2p,  xSp  and  x^p  for  the  four  arrays  ar.arrayl,  ar_array2, 
ar_array3  and  ar_array4.  Thus  on  any  iteration  of  the  inner  loop 
corresponding  elements  of  two,  three,  or  four  arrays  are  being  pointed  at. 
Each  of  these  arrays  has  its  own  base  element  address  and  element  pointer 
type.  However,  the  subscripts  are  restricted  by  the  sizes  of  ar.arrayl, 
which  should  be  the  smallest  of  the  arrays.  There  are  variables  yip,  y2p, 
y4Px  v4p  for  the  other  dimensions. 

Sar^or^elevients  (ar^array,  type)  is  an  abbreviation  for— 

sarjxfor^elements  (ar_array,  type,  (ar.array)— >  sor.c6ase). 

Sartor ^2^elcments,  sar^or^S^elements  and  sar^or^4^elements  are 
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similar  abbreviations  where  all  arrays  have  the  same  element  types  and 
■^ar^cbasc  may  be  used  for  the  ba.se  address  in  each  case. 

The  .\  in  sar_Tfoi_eleiiievlf<  stands  for  "extended".  The  forms  without  the 
X  are  more  commonly  used. 

EX.4MPLE: 

/*  Add  input!  to  inpuf2  and  store  in  output  * / 

{  sor_/or_.9_e/eme»/6  (output,  inputl,  input2,  lo}ig  *)  { 

*  Tip  =  *  t2p  +  *  jSp,  }} 

{sar_xfor_inatrices  (ar_arrav.  type,  base)  { 

...}} 

{sar_xfor_2_matr5ces  (ar_arrnyl,  typel.  basel. 

ar_arrav2.  lvpe2.  base2)  { 

...}} 

{sar_xfor_3_m  at  rices  (ai^arrayl,  typel.  basel. 

ar_array2.  tvpe2.  base2, 
ar_arrav3.  tvpe3.  base3)  { 

{sar_xfor_4_matrices  (ar_arrnyl,  typel  basel 

ar_array2.  type2.  base2. 
ar_array3.  type3.  base3. 
ar_arrav4.  ivpe*!.  base-4)  { 

... }} 

{sar_for_matrices  (ar_arrav.  type)  { 

...}} 

{sar_for_2_matrices  (ar_arravl,  ar_arraY2,  tvpe)  { 

... }} 

{8ar_for_3_matrices  (ar_arrayl,  ar_array2,  ar_array3, 

type)  { 

...}} 

{sar_for_4_matrices  (ar_arrayl,  ar_array2,  ar_array3, 

ar_array4,  tvpe)  { 

...  }} 

SIDE  EFFECT:  Sar^xfor^matrices  creates  a  loop  which  executes  the  body  ...  once  for  each 
2  dimensional  matrix  of  ar_array.  This  macro  is  equivalent  to— 


[C  Macro] 
[C  Macro] 

jC  Macro] 

jC  Macrol 

[C  Macro- 
[C  Macro] 
[C  Macro] 

(C  Macro] 
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type  zp:  uU  Z\ 
type  t]K  in  I  T\ 
type  up\  ini  U: 
type  V}K  iv(  V: 

?/(ar_array— >5(/r_e(ftr»cn5t<?r?6  ==  0) 
for  ( r  =  0,  vp  =  (type)  (base); 

V  <  (ar_array)— >5ar_r5trc; 

-h-h  V'  vp +=  (ar^array)— >5(jr_i?jyjcrer»cn/) 
for  ( U  =  0,  up  =  I’p: 

U  <  (ar_array)— >5ar_«5t2e; 

Uj  up  +=  (ar_array)—> 5ar_titr?crcrucnf) 
for  (7  =  0,  (p  =  up: 

T  <  far_array)— >5ar_/5t2c; 

++  T,  ip  -l-=  (ar_array)— >  5ar_//»c*rer7?crj/) 
for{Z  =  0,  zp  =  fp; 

Z  <  (ar_array)— >5ar_r5t^c; 

-h-f  Z,  2p  -f=  (ar^array)— >5ar_r?TKTcr77cn/) 

Notice  that  the  macro  begins  with  declarations,  and  that  more  declara¬ 
tions  may  immediately  precede  the  macro.  The  pointer  zp  tracks  through 
the  matrices  of  ar_array.  and  may  be  use  in  the  array  bo^y  as  the  address 
of  the  (0  0)  element  of  the  current  matrix.  The  type  of  this  pointer  is  the 
type  argument  to  the  macro.  The  address  of  the  (0  0  00  0  0)  element  of 
ar_array  is  the  base  argument  to  the  macro.  The  variables  Z,  7,  f/,  and 
Tare  the  subscripts  of  the  current  matrix. 

The  macros  $ar^xfor^2_matricc$,  sar^xfor^S^matriceSj  and 
sar^xfor^4~-matrtccs  are  similar  except  that  there  are  a  separate  set  of 
pointers  rip,  r^p,  zSp  and  z4p  for  the  three  arrays  ar_arrayl,  ar_array2, 
ar_array3  and  ar_array4.  Thus  on  any  iteration  of  the  inner  loop 
corresponding  matrices  of  two,  three  or  four  arrays  are  being  pointed  at. 
Each  of  these  arrays  has  its  own  base  element  address  and  element  pointer 
type.  However,  the  subscripts  are  restricted  by  the  sizes  of  ar_arrayl, 
which  should  be  the  smallest  of  the  arrays.  There  are  variables  tip,  t2p, 
tSp,  t4p,  ulp,  ...,  v4p  for  the  other  dimensions. 

Sar^or_ynatricts  (ar_^rray,  type)  is  an  abbreviation  for— 

5ar_z/or_mafncc5  (ar^array,  type,  (ar_array)—>  sar_c6ase). 

Sar_Jor^2^matricts,  sar_Jor^S^matrtces,  and  sar^or^4-^<^^^^^^^  ^re  simi¬ 
lar  abbreviations  where  all  arrays  have  the  same  element  types  and 
sar^ebase  may  be  used  for  the  base  address  in  each  case. 

The  X  in  snr_2/or_mairiccs  stands  for  ’’extended**.  The  forms  without  the 
X  are  more  commonly  used. 
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{sar_xfor_matrix_elements  (:»r_arrav.  tvpe,  base)  { 

{sar_xfor_2_matrix_elements  (nr_arrayl.  typel,  basel. 

ar_arrav2,  tvpe2,  base2)  { 

...  }} 

{sar_xfor_3_matrix_elements  (ai_ariay  1 .  type],  basel, 

ar_array2,  type2,  base2, 
ar_arrav3.  tvpe3,  base3)  { 

...  }} 

{sar_xfor_4_nnatrix_elennents  (ar_arrayl.  typel,  basel, 

ar«array2,  type2,  base2, 
ar_array3,  type3,  base3, 
ar_arrav4,  tvpe4,  base4)  { 

...  )}  ^ 

{sar_for_matrix_elennents  (ar_arrav,  tvpe)  { 

... }} 

{sar_for_2_matrix_elements  (ar_arravl,  ar_arrav2,  tvpe)  { 

...  }i 

{sar_for_3_matrix_elements  |ar_ariayl.  ar_array2.  ar_arrav3 

type)  { 

...}1 

{sar_for_4_matrix_elements  (ar_arrayl.  ar_array2,  ar_array3, 

ar_arrav4,  tvpe)  { 

... }} 

SIDE  EFFECT:  Sar^xfor^malrix^clcinenfs  creates  a  loop  which  executes  the  body  ...  once 
for  each  element  of  a  2  dimensional  matrix  in  ar_array.  This  macro  is 
equivalent  to— 

register  type  xp;  register  int  X\ 
register  type  yp;  register  int 
*/(ar_array— >sar_cdimcnsions  ==  0) 
for  ( y  =  0,  yp  =  (type)  (base); 

y  <  (ar_array)— >sar_y5i2e; 

-f-f  y,  yp  +=  (ar_array)— >5ar_yincrcTncn/) 
for  {X  =  0,  2p  =  yp; 

X  <  (ar_array)— 

+-f  X,  xp  -f=  (ar_array)— >sar_iincremen/) 

Notice  that  the  macro  begins  with  declarations,  and  that  more  declara¬ 
tions  may  immediately  precede  the  macro.  The  pointer  xp  tracks  through 
the  elements  of  a  matrix  of  ar_array,  and  may  be  use  in  the  array  body  to 
access  the  current  element.  The  type  of  this  pointer  is  the  type  argument 
to  the  macro.  The  address  of  the  (0  0)  matrix  element  is  the  base  argu¬ 
ment  to  the  macro.  The  variables  X  and  Y  are  the  subscripts  of  the 
current  element. 

The  macros  sar^xfor^S^nialriz^elemenis^  sar^xfor^S^matrix^elements  and 
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jC  Macro] 
jC  Macro] 

jC  Macro] 

jC  Macro] 

jC  Macro] 
[C  Macro] 
[C  Macro] 

[C  Macro] 
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sar^Tfor_.f_7italrl.r^eleniciif$  are  similar  except  that  there  are  a  separate 
sol  of  pointers  j7/>.  j;?//.  tS])  and  x^p  for  the  three  arrays  ar_arrayl, 
iir_ari  ayi.  ai_ni  i  ay3  and  ar_arrny-l.  Thus  on  any  iteration  of  the  inner 
loc»p  con  espoiiding  eleinciiis  of  two,  three  or  four  matrices  are  being 
pointed  ai.  Each  of  these  mai rices  has  its  own  base  element  address  and 
element  pointer  type.  However,  the  subscripts  are  restricted  by  the  sizes 
of  the  X  and  Y  dimensions  of  ar^arrayl,  which  should  be  the  smallest  of 
the  matrices.  There  are  variables  j/lp,  y2p,  ySp,  y4p  for  the  Y  dimension. 

S(it^or_tiiatrl.r_€lcincnls  (ar_arra>'.  type)  is  an  abbreviation  for— 
.‘inr_.r/or_///(//r/j_c/en/c/jf$  (ar^array,  type,  ap). 

and  is  intended  to  be  used  inside  sar^or^matriccs. 
Sur^or_2^niiiiri,r^clt))ieuts.  $ar^or_S^matrix^clcmcnt$  and 

fiar^for^.{_in(itrl.r^€leinenls  are  similar  abbreviations  where  all  arrays  have 
the  same  element  types  and  zip.  z2p.  zSp  and  z^p  are  used  as  the  base 
addresses. 


The  N  in  sar_rfor_7iiafri.r_elemeiifs  stands  for  ”extended’*.  The  forms 
witliout  I  he  N  are  more  eommonly  used. 

(set-array-by-expression  ’;u_:irray  ’g_expression)  [LISP  Function] 

WHERE:  The  element  type  of  ar_array  must  be  numeric. 

RETURNS:  Ar_array  after  its  elements  hn\  e  been  set. 

SIDE  EFFECT:  Sets  all  the  elements  of  ar_array  using  g^expression  to  compute  a  value 
for  each  element.  G_e\pression  is  an  expression  to  be  evaluated  for  each 
element.  In  that  e.xpression.  the  variables  X,  T,  Z,  T,  C/,  and  V  evaluate 
to  the  subscripts  of  the  element.  There  should  be  no  other  variables  in  the 
expression  (variables  may  be  substituted  for  in  the  expression  when  the 
expression  is  created  by  using  ‘  and  ,). 

(set-array-by-value  ’ar_array  ’  g_vahie)  [LISP  Function] 

RETURNS:  Ar.array  after  setting  its  elements. 

SIDE  EFFECT:  Sets  the  elements  of  ar_array  using  values  taken  from  g_value.  G.value  is 
a  list  of  sublists  of  sublists  ...  of  element  values.  The  innermost  lists 
correspond  to  the  first  (X)  dimension:  e.g.,  if  x  is  an  array  with  sizes  (2  3) 
then— 

[set-array-by-valuc  x  ’((00  01)  (10  11)  (20  21))) 

and— 

{$et-array-by‘Cxprc$$ion 

X  \plxis  X  {product  10  F))) 

set  the  elements  to  the  same  values. 

NOTE:  If  elements  or  sublists  are  omitted  from  the  end  of  a  list,  nil  values  will  be 
assumed. 
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(slice-of-array  ar_nrray)  [LISP  Function] 

(slice-of-array  nr_nrray  ^(x_5<izc  ...)  [’(x_origin  ...)  p(x_ste|)  ...)!])  [LISP  Function] 

(slice-of-array  nr_ai  ray  x_(liiiiension  x_^ize  jx_origin  jx_siep]|)  [LISP  Function] 

RETURNS:  If  only  tlie  ar_arrny  argument  is  given,  a  new  array  whose  parent  is  identical 
to  the  current  slice  of  ar_array.  and  whose  current  slice  is  identical  to  its 
parcMit  The  elemenis  of  ar_array  are  first  allocated,  if  this  has  not  already 
been  done. 

If  other  arguments  are  given,  {slice-of-array  ar_array  ...)  is  equivalent  to 
{place-array  {stice-oj-array  ar_array)  ...). 

NOTE:  The  new  array  shares  the  elements  of  ar_array.  so  that  changes  to  these  ar^array 
elements  will  change  the  corresponding  new  array  elements  and  vice  versa. 

NOTE:  The  has-beev-chaayed  and  is-readoviy  attributes  of  the  new  array  are  set  to  the 
corresponding  aiirihuies  of  the  old  army.  The  is-itnv}ovahle  attribute  is  set  to 
ail. 


(summary-of-array  *ai_army)  [LISP  Function] 

WHERE:  The  elcnieiiis  of  ar_rirray  must  be  numeric. 

RETURNS:  A-stifninary  siniciure  summarizing  the  army.  All  the  usual  an-array- 
.sn /;//?;(/;•// struct  lire  niiribuies  are  included. 


(sweep-array-b  locks) 
*sweep-array-blocks-count* 

*s  weep-array- blocks-time* 
*sweep-array-blocks-by  tes* 

USE  ONLY  WHEN:  Playing  w  ith  the  array 
automatic). 


[LISP  Function] 
[LISP  Global  Variable] 
[LISP  Global  Variable] 
[LISP  Global  Variable] 

block  garbage  collector  (w^hich  is  normally 


SIDE  EFFECT:  Marks  as  free  all  unused  blocks  in  the  array  block  memory  allocation  area 
so  they  may  be  reused.  Does  not  compact  the  block  allocation  area:  call 
compact-array-blocks  subsequently  to  do  that. 


*sxveep- array-blocks- count*  is  incremented  every  time  sweep- array- blocks 
is  called,  *sweep-array-blocks-time*  has  the  time  taken  by  the  call  added 
to  it,  and  *sweep-array-blocks-bytes*  has  the  number  of  bytes  recovered 
by  the  sweep  added  to  it.  All  these  variables  are  initialized  to  0.  The 
time  is  measured  in  the  same  units  as  ptime:  see  *ptime-counts-per- 
secoxxd*. 

RETURNS:  The  sum  of  the  number  of  fixnum’s  in  all  the  free  blocks. 
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(transpose-array  ‘ar_array  \\_diniension-l  \\_(limension-*2)  (LISP  Function] 

RETURNS:  Ar.array  after  it  is  modified. 

SIDE  EFFECT:  Transposes  (exchanges)  the  two  specified  dimensions  within  bofh  the 
current  ar_array  slice  and  its  parent.  The  actual  data  elements  are  not 
moved:  rather  all  the  dimension  parameters  in  the  array  object  are 
exchanged. 

(uneval-object  ’ar_array  [<])  (LISP  Function] 

*default-array-file*  [LISP  Global  Variable] 

cache.ar  [UNIX  File  Name] 

EQUIVALENT  TO:  The  usual  uneval-object,  except  that  if  the  array  has  a  /  has-been- 
changed  Mnhutc,  then  — 

(xvrife-arroy-eleinenfs  ar_array  *  default- array- file*) 

is  called.  Also  ar_ar ray's  has-parent-sizes,  has-parent-increinents, 
has- desired- sizes,  has- desired- origins,  has- steps,  has-parent- offsets, 
has-parenf-scales,  and  has-parities  values  are  output  with  some  edit¬ 
ing.  The  ends  of  the  list  values  of  these  attributes  are  truncated  in  the 
same  manner  as  the  do-shorten  option  truncates  the  lists  when  they 
are  gotten.  Also,  has-parent-sizes  is  renamed  has-sizes,  has-parent- 
increnienfs  is  renamed  has-increntenfs,  has-parent-offsets  is  renamed 
has-offsefs,  and  has-parent-scales  is  renamed  has-scales. 

NOTE:  *  default-array- file*  is  a  global  variable  whose  default  value  is— 

[cache. ar  end-of-file). 

(write-array-elements  ’ar_array  ’g_ar ray- file)  [LISP  Function] 

SIDE  EFFECT:  Writes  the  parent  of  ar_array  to  the  file  location  specified  by  g_array-file. 

Sets  the  has- array- file  attribute  of  ar_array  to  g_array-file,  and  the  has- 
ar  ray- for  mat  attribute  to  the  value  of  *  computer- format*.  Sets  the  has- 
been-changed  attribute  to  nil. 

See  HAS- ARRAY-FILE  under  an-array  for  the  format  of  g_array-file. 

NOTE:  G_array-file  may  have  one  of  the  forms— 

(s_file-name  end-of-file) 

(s_volume-name  end-of-volume) 

(s_volume-name  x_file-number  end-of-file). 

In  these  cases  the  last  element  of  the  g_array-file  list  will  be  changed  to  an 
appropriate  number  before  it  is  stored  in  the  has- array- file  attribute. 
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('write-catalog  Va_catalog  'ar.array)  [LISP  Function) 

SEE:  Vnexwl^object  (in  this  chapter),  which  is  called  to  produce  the  exact  value  to  be 
written  into  the  catalog 


X*dimension 

Y-dimension 

Z-dimension 

T-dimension 

U-dimension 

V-dimension 

VALltE:  The  integers  0  (X^dimeiisiov)  th 
dimensions  of  arrays. 


[LISP  Global  Constant] 
[LISP  Global  Constant] 
[LISP  Global  Constant] 
[LISP  Global  Constant] 
[LISP  Global  Constant] 
[LISP  Global  Constant] 

gh  5  ( V-dtmcnsion)  identifying  the  different 


NOTE;  The  X  dimension  is  first  when  listing  subscripts,  dimension  sizes,  etc.,  and  the  V 
dimension  is  last. 


NOTE:  The  standard  storage  organization  for  arrays  is  a  contiguous  list  of  elements  with 
the  X  subscript  varying  fastest  and  the  V  subscript  slowest.  Other  organizations 
may  be  obtained  by  explicitly  specifying  the  has^parcnt^iucremcnis  attribute. 
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1.  GLOSSARY. 

(absolute-value-array-elements  ‘lai.oiitpui  plar_input])  |L1SP  Function] 

WHERE:  Both  arrays  arc  similar  and  lai.inpiii  defaults  to  lar_oiitput. 

RETl'RNS:  Lar_ontpiit  after  its  clenuMit'^  have  been  set. 

SIDE  EFFECT  Sets  each  element  m  lni_outpiii  to  the  absolute  value  of  the  corresponding 
elemeni  in  lai_in])ii)  The  )\\o  arrays  ma\  have  different  exponents. 

(accumulate-filter  ‘lai_ariay  \_dimeiision)  jLISP  Function' 

RETURNS:  Liir_array  is  reiuriied  after  ihe  lai_nrray  elements  are  modified  to  hold  the 
desired  result. 

SIDE  EFFECT.  Applie:?  a  filler  tha)  computes  the  sum  of  all  values  with  equal  or  lower 

subscripts  for  the  given  dimension  of  the  given  lar_array.  Thus  the  out¬ 

put  for  subscript  j  in  the  given  dimension  is  the  sum  of  the  input  for  sub¬ 
scripts  0.  1 ,  ....  j. 

BUGS:  Overflow  is  handled  by  doing  modulo  arithmetic. 

(add-arrays  ’lar_outpul  Mar_inpui-1  [‘lar_input-‘2j)  [LISP  Function] 

WHERE:  The  arrays  are  similar  and  have  the  same  exponent,  and  lar_input-2  defaults  to 
lar^output. 

RETURNS:  Lar^outpul  after  its  elements  have  been  modified. 

SIDE  EFFECT;  Adds  each  element,  of  lar_input-l  to  the  corresponding  element  of 

lar_input-2  and  stores  the  result  in  the  corresponding  element  of 

lar^output. 

BUG:  The  addition  is  done  using  modulo  arithmetic  in  event  of  overflow. 


BASIC  ARITHMETIC 


8-1 


BASIC  ARITHMETIC 


8-2 


(add-to- array-elements  *n_;uklciicl )  jLlSP  Functionj 

RETVnN.^  L:ir_:nm\  niter  it^  (‘lenient'^  h:iV(‘  been  modified. 

SIDE  EFF  IX  T  .■\(ld>  ii^nddriid  10  :ill  elenieni>  of  lar^array. 

BUG;  Tiiv  nddnioii  doiu-  modulo  nnihmetie  in  llie  event  of  overflow. 

(arccos-array-elements  put  ’l.ii_iiiput  J  |LISP  Function; 

WHERE:  Both  nriny^  nre  similnr  ;iikI  lni_input  del’niilts  to  lar^output. 

RETURNS-  Lnr.outpui  nftei  ii>  ekinents  ha\e  been  set. 

SIDE  EFFECT:  Sei.s  ench  element  in  lnr_outpiit  to  the  arc  cosine  of  the  corresponding  ele- 
ineiii  in  l:ir_input.  'The  iwo  arrays  may  have  different  exponents. 

(arcsin-array-elements  ’l:ir_oi:i  put  d;ir_inputj)  [LISP  Function] 

WHERE:  Both  ,irrny.<  nre  similni  niul  l:ii_input  defaults  to  lar_output. 

RETURNS;  Lnr_oiit  ptit  niter  it'-  elenieni'-  have  been  set. 

SIDE  EFFECT:  -Seis  e;e  li  eleim-nt  in  lai_oiitpiit  to  the  arc  sine  of  the  corresponding  ele¬ 
nieni  in  ljr_inpiit  The  n\o  arrays  may  have  diflerent  exponents. 

(contrast-of  *:ti_in|  111  *(x_\Mdili  ..)  [LISP  Function 

i;_l'.iekci  OUlid  n^eelller  I 

WHERE:  The  \_wi(Iili  nre  no;i-negnt ive  integers  and  both  n^backgrouiul  and  n_center 
deliiult  to  1  0. 

RETURNS:  An  output  army.  l;n_output.  whose  elements  are  the  "convolution”  in  the 
sense  of  the  conroire  function  of  ar_input  and  a  kernel  with  a  special  form 
which  is  parametrized  by  (N_\vidth  ...).  n_background,  and  n_center.  The 
kernel  is  of  size- 

(2  *  \_width  -h  1,  ...) 

and  has  for  all  its  elements  except  the  center  element  the  value- 
-  n_background  /  ((2  *  x_widih  -I-  1)  *  ...). 

where  the  denominator  is  the  area  of  the  kernel.  The  center  clement  has  the 
value- 

n_center  -  n^background  /  ((2  *  x_width  -hi)* 

The  effect  is  to  output  into  each  lar_output  element  (X,  ...)  n^center  times 
the  ar_input  element  (X-fx_widtli.  ...)  minus  n_background  times  the  average 
of  the  ar_input  elements  in  a  (2*x_width-i-l  ...)  rectangular  box  centered  on 
the  ar_input  element  just  indicated. 

BUGS:  Missing  values  are  not  handled.  Overflow  is  handled  by  doing  modulo  arithmetic. 
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(convolution-of  ■;ir_iripui  ‘nr^kt  rnell  ILISP  Funciion' 

PirTrRN'-:  A  Wkw  '2  diiiieii'^ioiial  annv  Inr^oiiipui  wirli  evj^onent  the  same  as  ar_inpiit 
(alter  its  elements  are  converted  to  a-lon(fs)  whose  elements  are  computed  by 
pa.s>iiig  It  and  the  other  parameters  to  the  convolution  function  Prejnirt' 
arruif  is  applied  to  ar_in))Ui 

(convolve  lar.outpiit  ■|ar_inpiit  ’ai^kernel)  jLlSP  Funct ion) 

\\‘H1-RE:  The  arrays  are  treated  ;xs  2  dimensional,  and  the  sizes  of  the  lar_output  dimen¬ 
sions  imisi  be  one  more  than  sizes  of  the  corresponding  lar_input  dimensions 
minus  I  he  sizes  of  the  corresponding  ar_kernel  dimensions. 

RETt'RNs-  Lar_oiitpiit  after  its  elements  are  set 

SIDE  EFFECT  Stores  the  ’’convolution"  of  lar_input  and  ar_kernel  in  lar_output.  To  be 
more  preci-^e.  whai  is  stored  is  the  convoliiiion  of  lar_input  and  the  matri.N 
whose  (X  ^  )  th  element  is  the  (-X.  )’tli  element  of  ar_kernel:  or  in  other 
words,  the  (X.  ^  )  th  element  of  lar_outj)iM  i.s  the  scatnr-prodiicf  of  the 
;ii_kernel  and  a  sliee  of  lar_input  with  origins  (X.  Y). 

(cos-array-elements  lar_oulpiii  *lar_mpnt  )  !L1SP  Funct ion 

\\HERE  Both  arrays  are  similar  and  lar_inpni  defaults  lo  lar_output. 

RETURNS  Lar_oiiipiii  after  ii'^  elements  have-  been  .sei 

SIDE  EFFECT,  ^eis  each  elemeni  in  lai_otitpin  to  the  cosine  of  the  corresponding  element 
m  lai.input.  The  two  arrays  ma.\  have  dilierent  exponents. 

(del2g-kernel  ’(n_\width  n_y width)  (LISP  Function] 

/(n_xofTset  ii_yof]set)  ) 

WHERE:  N_xofl*set  and  n_voffset  are  >  0  and  default  to  0.5. 

RETURNS:  A  block  floating  point  array  with  exponent  -24  representing  the  kernel  com¬ 
puted  SIS  the  minus  of  the  Laplacian  operator  applied  to  the  Gaussian  func¬ 
tion.  The  Laplacian  operator  is  assumed  to  be  scaled  by  n_xwidth  and 
n_ywidth,  so  actually  the  second  derivative  with  respect  to  x  is  multiplied  by 
n^xwidth  **  2,  and  the  second  derivative  with  respect  to  y  by  n_>'width  **  2. 
The  sizes  of  the  X  and  Y  dimensions  are 

2  *  xsize  -F  {ceiling  n^xoffset)  +  1 

and 

2  *  ysize  +  (ceiling  n_yoffset)  4-  1 

where  xsize  and  ysize  are  choosen  as  indicated  below’.  The  value  of  the  point 
with  subscripts  (X  Y)  is- 

(1  /  (pi  *  n^xwidth  *  n_y width)) 

*  (1  -  (n_X  /  n_xwidth)  **  2  -  (n_^‘  /  n_yw'idth)  **  2) 

*  (exp  (1  -  (n_X  /  n.xwidth)  **  2  -  (n_Y  /  n.ywidth)  **  2)) 
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where 

n_X  =  \  -  xsize  •  n_\oflset 
and 

n_Y  =  Y  -  ysize  -  n_yoflset. 

This  function  is  positive  inside  the  ellipse 

{n_X  '•  n^xwidth)  **  2  4-  (ii_Y  n_ywidth)  2  <  1, 

zero  on  that  ellipse,  and  negative  outside  the  ellipse.  The  total  integral  of  the 
function  is  0.  The  function  is  normalized  to  have  the  integral  4-1  inside  the 
ellipse  and  the  integral  -1  outside  the  ellipse,  where  for  these  purposes  the 
function  is  assumed  lo  be  continuous  and  extend  to  infinity. 

Xsize  and  ysize  are  chosen  to  be  large  enough  so  that  the  integral  of  the  con- 
linuou.^  function  over  all  point.s  (X  Yl  outside  the  kernel  returned  by  (/e/Jy- 
kerne!  is  le.S5  than  the  value  of  the  global  variable  *keri}el'Ctitoff*.  In  comput¬ 
ing  these  sizes.  n_xofrset  and  n_yoflset  are  assumed  to  be  0.  as  a  worst  case. 

(derivative-filter  dar_array  ’x_dimension  ’x_width)  [LISP  Function^ 

RETURNS:  A  slice  of  lar_array  is  returned  after  the  lar_array  elements  are  modified  so 
that  the  slice  holds  the  desired  result.  The  size  of  the  given  dimension  for  the 
slice  is  x_width-l  less  than  the  size  of  that  dimension  for  lar_array,  and  the 
slice  origin  is  0  for  that  dimension.  Other  dimensions  are  not  affected. 

SIDE  EFFECT:  Applies  a  derivative  filter  of  the  given  x.width  for  the  given  x_dimension 
of  the  given  lar_array.  The  derivative  filter  forms  the  sum  of  the  terms - 

(6  /  (x^width  **  3  -  x^width))  *  (-  x_width  4-1  -f  2  *  i)  *  x  (i) 

for  i  =  0,  1,  ...,  x_\vidth  -  1.  The  normalization  constant  is  chosen  so  that 
if  x(i)  =  i  the  result  will  be  1.  The  output  for  subscript  j  in  the  given 
dimension  is  computed  by  letting  x(i)  equal  the  input  for  subscript  j4-i. 

NOTE:  The  lar_array  elements  that  are  not  in  the  returned  slice  are  modified  in 
undefined  ways. 

BUGS:  Missing  values  are  not  handled.  Overflow  is  handled  by  doing  modulo  arithmetic. 
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(dither  x^sizc)  Ll^P  FunctioiP 

(cached-dither  \_size) 

*  default-dither-size* 

WHERE:  X_si2(*  a  power  of  two. 

RETURNS:  Dither  and  cacheti-dither  return  the  Dither  Matrix  of  the  given  size  the 
matrices  D"  of  the  paper  Jarvis,  J.F.,  Judice,  C.N.,  and  Ninke.  W.H..  A  Sur¬ 
vey  of  Tehviijue^  for  the  Display  of  ConUnuovs  Tone  Pictures  on  Bilevel 
Dh^plays,  Computer  Graphics  and  Image  Processing..  5,  13-40  (1976).  where  n 
is  the  matrix  size.  N_size.  The  matrix  is  square. 

Cachcd’dither  remembers  all  dither  matrices  it  has  computed,  saving  them. 
It  returns  pre\  lously  coinpured  matrices  without,  recomputing  them.  Only 
those  of  size  <=  64  are  saved  at  the  moment. 

*defaulf-difhcr-si:e*  is  a  global  variable  set  to  a  default  value  suitable  lor  the 
size  parameter  It  itself  defaults  to  S. 

(dxg-kernel  '(n_\\vi(hh  n_ywiclth)  iLlSP  Function 

’(n_xonsei  n_yoll>et)  ) 

WHERE  N_xonset  and  n_yofisei  are  >  0  and  default  to  0  5. 

RETURNS:  A  block  lloating  point  array  with  exponent  -*24  representing  the  kernel  com- 
])iited  as  the  minus  of  the  x  partial  derivative  applied  to  the  Gaussian  func¬ 
tion  The  sizes  of  the  X  and  Y  dimensions  are 

2  *  xsize  -I-  {ceiling  n_xoffset)  -h  1 


and 

2  *  ysize  -h  (ceiling  n_yoffset)  -f  1 

where  xsize  and  ysize  are  choosen  as  indicated  below.  The  value  of  the  point 
with  subscripts  (X  Y)  is- 

(2  /  pi)  *  n^xwidth  *  n^ywidth)) 

*  (n_3c  /  n_xwidth) 

*  [exp  {-  (n_X  /  n_xwidth)  **  2  -  (n_Y  /  n_ywidth)  **  2)) 
where 

n_X  =  X  -  xsize  -  n_xoffset 
and 

n_Y  =  Y  -  ysize  -  n_yoffset. 

This  function  is  positive  for  X  >  0  and  negative  for  X  <  0. 
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The  total  integral  of  the  function  is  0.  The  function  is  normalized  to  have  the 
integiiil  +1  on  the  halfplane  X  0  and  the  integral  -1  on  the  halfplane  X  < 
0.  where  for  these  purposes  the  function  assumed  to  be  continuous  and 
extend  to  infinity. 

Xsize  and  ysize  are  chosen  to  be  large  enough  so  that  the  integral  of  the  con¬ 
tinuous  function  over  all  points  (X  )  outside  the  kernel  returned  by  dxg- 
kernel  is  less  than  the  value  of  the  global  variable  *keri} el-cutoff*.  In  comput¬ 
ing  these  sizes.  n_xoffset  and  n_yofTset  are  assumed  to  be  0,  as  a  worst  case. 

(expand-missing  ‘lar_output  'arjnput  ’ar_original  [LISP  Function] 

!'{x_xsize  x_ysize)  (’\_count]|) 

NVHERE:  Lar_output,  ar_inputj  and  ar_original  all  have  the  same  exponent  and  the  same 
dimension  sizes  except  for  the  X  and  dimen.sions.  Lar_output.  and  ar_original 
have  the  same  X  and  Y  dimensions,  while  the  X  and  dimensions  of  ar_input 
are  respectively  2*.\_xsize  and  2*x_ysize  larger  than  the  X  and  dimensions  of 
lai\_output. 

X_xsize.  X_ysizc.  and  x^count  all  default  to  1 

HETIRN.^;  The  number  of  non-missing  elements  of  ar_input  replaced  by  missing  values 
in  lar_ouiput. 

SIDE  EFFECT  Copies  the  elements  of  ar_input  to  lai_output.  replacing  some  of  the  non¬ 
missing  values  by  missing  values.  The  purpose  of  this  is  to  expand  a  sky 
region  (region  of  all  missing  values  in  a  laser  radar  image)  which  has  been 
shrunk  by  shrink- missing.  Ar_original  is  the  original  array  before  it  was 
shrunk  by  shrmk-missing. 

An  element  is  replaced  by  a  missing  value  when  it  is  copied  if  (l)  the  ele¬ 
ment  is  not  missing  in  ar_input,  (2)  the  element  is  missing  in  ar_original, 
and  (3)  there  are  x_count  or  more  missing  values  in  the  box  in  arjnput  of 
size 


(2*x_xsize+l  2*x_ysize-fl) 

centered  on  the  element,  not  counting  the  element  itself. 
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(expand-missing-of  ar^inpiii  ar_onginal  [LISP  Function! 

(.\_N-sizc  x^vMZc)  !’.\_couiil  ■.\_iepeai  ...Ijj) 

WHERE:  Ar_inpui  and  ar^originnl  i^hoiilcl  have  the  same  dimension  sizes.  X^repeat 
defaults  to  infinity,  and  may  also  be  given  as  nil  to  specify  infinity. 

The  part  of  the  argument  list  beginning  with  *(\_xsize  x^ysize)  may  be  repeated 
as  long  as  any  repetition  begins  with  a  non-empty  list  value. 

RETURNS:  A  new  array  lar_oulpiit  which  is  computed  by  passing  arjnput  and  the'other 
parameters  through  eijuind-niisstug  x.repeat  times.  As  an  optimization,  the 
process  stops  \\  hen  no  more  replacement  is  possible,  so  x.repeat  can  be  a  very 
large  number 

If  no  replacement  is  done  in  computing  lar_output,  ar_inpiit  is  returned  in 
place  of  lar_out  put . 

Prepare -array  is  applied  to  ar_inpiit 

If  more  than  one  set  of  size  'county  repeat  parameters  is  given,  these  parame¬ 
ters  arc  removed  from  the  parameter  list  as  they  are  used,  and  the  process  is 
repeated  with  the  last  hir_output  substituted  for  ar_input. 

(exponentiate-array-elements  dar_output  |‘lar_inputj  [LISP  Function 

WHERE.  Both  arrays  are  similar  and  lar_input  defaults  to  lar.oulput 
RETURNS  Lar.output  after  its  elements  have  been  set. 

SIDE  EFFECT:  Sets  each  element  in  lar_outpui  to  the  exponential  function  of  the 
corresponding  element  in  lar_inpui.  The  two  arrays  may  have  different 
exponents- 

(gaussian-kernel  *(n_xwidth  n_y width)  [LISP  Function] 

(’(n_xoffset  n_yofIset)]) 

WTiERE:  N_xoffset  and  n.yoffset  are  >  0  and  default  to  0.5. 

RETlTtNS:  A  block  floating  point  array  with  exponent  -24  representing  the  kernel  com¬ 
puted  by  the  Gaussian  function.  The  sizes  of  the  X  and  Y  dimensions  are 

2  *  xsize  +  [ceiling  n_xofrset)  +  1 

and 

2  *  ysize  -h  [ceiling  n_y offset)  -F  1 

where  xsize  and  ysize  are  choosen  as  indicated  below.  The  value  of  the  point 
with  subscripts  (X  Y)  is- 

(1  /  (pi  *  n_xwidth  *  n.ywidth)) 

*  [exp  (-  (n_X  /  n^xwidth)  **  2  -  (n.Y  /  n.ywddth)  **  2)) 
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wlu-  If 

M_\  =  X  -  NMZi*  -  ll^XOll'^Cl 

itiul 

M_V  =  V  -  y^Vsiv  •  n^yollsci 

Xsizc  tiikI  ysizc  art'  clu^^en  to  be  large  enough  so  that  the  integral  of  the  con- 
linuon-  function  over  all  points  (X  Y)  outside  the  kernel  returned  by 
gnassKtn-kcniel  is  less  than  the  value  of  the  global  variable  *ktrvd-cxiioff*.  In 
coinpining  ihe^^e  size.'^.  n_\offset  and  n.yoffset  are  assumed  to  be  0.  as  a  worst 

CilM-. 


'j'lie  iK*i iiKilizai ion  constant  is  chosen  so  that  the  integral  of  the  kernel  would 
1)0  I  i!  It  wlii  if  a  coniinuons  lunction  extending  to  infinity. 

(interpolation-filter  ’l;ii_:irrny  ‘N_diinension  ’n.factor  [LISP  Function’ 

’n_Oir>rt  ) 

RETl'RNs  A  >lu  -  ol  l.ir_:in;iy  is  returned  after  the  lar.array  elements  are  modified  so 
I  fill  I  il.-  .-Ih  f  fi.jkL  the  de-ired  result.  The  size  of  the  given  dimension  lor  the 
slicv  I"  a"  large  US  possible  subject  to  the  conditions  that  for  all  slice  sub- 
x  rip:.-  j 


-  epsilon  <  n.oflset  4*  j  n.factor 

<  .xjnput-dimension-size  -  1  -I-  epsilon. 

where  epsilon  =  2'*^  is  included  to  compensate  for  rounding  errors.  The  slice 
origin  is  0  for  that  dimension.  Other  dimensions  are  not  affected. 

SIDE  EFFECT:  Interpolates  the  input  values  for  the  given  dimension  so  that  the  output 
has  the  given  size.  Linear  interpolition  is  used.  Output  subscript  0  has 
the  value  associated  with  input  subscript  n_offset,  and  in  general  output 
subscript  j  has  the  value  associated  with  input  subscript 

n.offset  -b  j  *  n_factor 

Non-integer  input  subscripts  given  by  this  formula  are  handled  by  linearly 
interpolating  input  elements  with  the  next  lower  and  higher  integer  sub¬ 
scripts.  Input  subscripts  less  than  0  by  an  amount  less  than  or  equal  to 
epsilon  are  treated  as  0,  and  similarly  input  subscripts  larger  than  the 
maximum  input  subscript  by  an  amount  less  than  or  equal  to  epsilon  arc 
treated  as  the  maximum  input  subscript. 

NOTE:  The  lar.array  elements  that  are  not  in  the  returned  slice  are  modified  in 
undefined  ways. 
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(interpolation-of  ar^inpui  ‘(N_si2e  ))  [LISP  Functionf 

WHtRE  The  N_si7e  are  non-negaiive 

RETI  RNS:  An  output  arrav.  Inr^outpiit.  who'se  elenieniij  are  the  linear  interpolation,  in 
the  sen>-e  of  the  inferpnlafioih filler  function,  of  the  elements  of  ar^input  The 
dimension  sizes  ol  hir_output  are  (\_size  ...)  The  expansion  factors  for 
inltrpolafioii‘ filler  are  automat icniiy  chosen  to  be  positive  and  to  gi^•e  the 
nglit  lar^output  sizes  (and  the  oflsets  are  chosen  to  be  zero). 

Bt’Ci  Overfiou  i"^  handled  by  doing  modulo  arithmetic.  ^ 

’^kernel-cutoff*  [LISP  Global  Variable] 

\ALt’E:  A  fintnini.  default  0.01.  The  amount  of  a  kernel  that  may  be  discarded  in  order 
to  make  a  kernel  of  infinite  extent  lit  into  a  small  finite  arra} .  Measured  as  a 
fraction  bounding  the  integral  of  the  discarded  part  of  the  kernel  divided  by  the 
integral  of  the  kernel  over  the  pan  of  the  space  where  the  kernel  has  the  same 
.sign  ii  do'’S  in  the  discarded  part  The  measurement  is  generally  made  by  using 
integr.ii loii  of  the  coniinuou^  kernel  function,  not  its  descrete  representation. 

(local-maxima-of  ’ar^inpui  '(.\_.‘<izc  ...))  [LISP  Function'; 

WlIEnr.  The  are  noii-negnt  ive 

RETl’H.x.'':  .An  cut  put  arruv  l;ti_oinj)ut  whose  element^  are  the  maxima  of  the  elements 
of  a  rectangular  box  centered  at  the  corresponding  point  of  lar_input  The 
size^  of  the  box  are  (2\\_size-hl .  ...).  The  maximum  is  computed  successively 
along  each  dimension  of  ar_input  by  calling  the  function  maximum-filter  for 
that  dimension  The  dimensions  of  lar_output  are  made  identical  to  the 
dimensions  of  ar^inpui.  by  first  expanding  lar_input  by  appropriate  amounts. 
This,  and  the  conversion  of  element  type  to  a-long,  are  accomplished  by  pass¬ 
ing  the  input  array  to  the  function  prepare-array.  The  input  array  is 
returned  only  when  it  ha5  type  a-long  and  the  x_size  ...  arguments  are  all 
zero. 

(locaLminima-of  'ar_input  *(x_size  ...))  [LISP  Function] 

WHERE-  The  x_size  ...  are  non-negative. 

RETURNS:  An  output  array,  lar_output,  whose  elements  are  the  minima  of  the  elements 
of  a  rectangular  box  centered  at  the  corresponding  point  of  lar^nput.  The 
sizes  of  the  box  are  (2*.\_size-hl,  ...).  The  minimum  is  computed  successively 
along  each  dimension  of  ar_input  by  calling  the  function  minimum-filter  for 
that  dimension.  The  dimensions  of  lar^output  are  made  identical  to  the 
dimensions  of  ar_input,  by  first  expanding  larjnput  by  appropriate  amounts. 
This,  and  the  conversion  of  element  type  to  a-long,  are  accomplished  by  pass¬ 
ing  the  input  array  to  the  function  prepare-array.  The  input  array  itself  is 
returned  only  when  it  has  type  a-long  and  the  x_size  ...  arguments  are  all 
zero. 
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(log-array-elements  ’Ini^oiiipni  Ini.inpnl’)  [LISP  Function- 

\VHEHE:  Both  arrnys  are  siniilnr  and  lar_iiiput  defaults  to  lar.output. 

RETURNS:  Lar_oiitpiit  after  its  elements  have  been  set. 

SIDE  EFFECT;  Sel.>  each  eleiiieni  in  lar_oulpiU  to  the  logrithm  of  the  corresponding  ele¬ 
ment  in  larjnpui.  The  two  arrays  may  have  different  exponents. 

(mark-missing  'lar_oiiipiii  ’ar_input  [LISP  Function] 

’( n i  n  i  m  11  ni  n _m  a  x  i  m  ii  ni ) 

|*(n_lower  n_iipper)  ;’(x_x.size  x_ysize)  I'x^coiintj]]) 

WHERE:  Lar_oiiipiil  and  larjnpui  have  the  same  exponent  and  the  same  dimension 
sizes  excej)t  for  the  X  and  dimensions.  The  X  and  Y  dimensions  of  larjnput 
are  respectively  2*.\_xsizt’  and  2*,\_ysize  larger  than  the  X  and  Y  dimensions  of 
lar.outpiit.  N_miniimiim.  n_ninxinium,  x_xsize,  x_ysize,  x_count,  njower, 
and  n_uj)per  may  be  given  a>  nil  if  they  are  missing.  X_xsize  and  X_ysize 
default  to  1.  and  \_(oiiiit  defaults  to  2.  N_niiiiimum  and  njower  default  to 
negative  inliniiy.  while  n_niaxinium  and  n_iipper  default  to  positive  infinity. 

RETURNS:  The  number  of  missing  values  in  lar^oiitput. 

SIDE  EFFECT:  Copies  ai_inpiii  to  lar_oulput  replacing  bad  pixel  values  by  the  missing 
viilue  nil  N'alues  oul.side  the  range  from  minimum  to  maximum, 
inchi.^ive.  are  bad. 

If  either  n_lower  or  n_upper  is  given,  then  a  value  is  replaced  by  nil  unless 
the 


(2*x_\size-f  1  2*x_ysize4-l) 

box  centered  on  the  pixel  contains  at  least  x_count  pixels  (not  counting 
the  center  pixel)  in  the  range 

(pixel-value-hnjower  pixel- value-l-n_upper). 

inclusive. 

(mark-missing-of  ’arjnput  ’(n_minimum  n^maximum)  [LISP  Function] 

[’(njower  n_upper)  [’(x^xsize  x_ysize)  [’x^count]]]) 

RETURNS:  A  new  array  lar_output  which  is  computed  by  passing  it  and  the  other 
parameters  to  the  inark-jnissing  function.  Prcparc-array  is  applied  to 
arjnput. 
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(max'imize-array-elements-with  ■|or_array  n.iuimber)  iLISP  Function] 

HETt  HNS:  L:ti_?irrny  after  its  elements  have  been  modified. 

SIDE  EFFECT;  Each  element  of  the  array  is  replaced  by  the  maximum  of  the  element 
value  and  n_number.  In  other  words,  elements  with  values  below 
n^iiumber  are  replaced  by  n_number. 

(maximize-arrays  ’lar_output  dar_inpiit-l  plar_input-2])  [LISP  Function] 

WHERE:  The  arrays  are  similar  and  have  the  same  exponent,  and  lar_input-’2  defaults  to 
lar_out  put 

RETURNS:  Lar.output  after  its  elements  have  been  modified. 

SIDE  EFFECT;  Takes  the  maximum  of  each  element  of  lar_input-l  with  the  correspond¬ 
ing  element  of  lar_input-2  and  stores  the  result  in  the  corresponding  ele¬ 
ment  of  lnr_out pul . 

(maximum-fi Iter  lai_array  'x_dimension  ’x_width)  [LISP  Function] 

RETURNS:  slice  of  lar_array  is  returned  after  the  lar_array  elements  arc  modified  sc 

that  the  slice  holds  t  he  desired  result  The  size  of  the  given  dimension  for  t  he 
slice  IS  x_width-J  le.ss  than  the  size  of  that  dimension  for  lar_array.  and  the 
slict  origin  is  0  for  that  dimension.  Other  dimensions  are  not  aflected 

SIDE  EFFECT:  Applies  a  filter  which  forms  the  maximum  of  the  last  x_width  ini)Ut  values 
for  the  given  dimension  of  the  given  lar_array.  Thus  the  output  for  sub¬ 
script  j  in  the  given  dimension  is  the  maximum  of  the  input  for  subscripts 
j.  j-t-1.  ....  j-hx_width-l. 

NOTE;  The  lar_array  elements  that  are  not  in  the  returned  slice  are  modified  in 
undefined  ways. 

BUG:  Missing  values  are  not  handled. 

(minimize-array-elements-with  Tar_array  ’n_number)  [LISP  Function] 

RETURNS:  Lar_array  after  its  elements  have  been  modified. 

SIDE  EFFECT:  Each  element  of  the  array  is  replaced  by  the  minimum  of  the  element 
value  and  n_number.  In  other  words,  elements  with  values  above 
n_number  are  replaced  by  n_number. 

(minimize-arrays  ’lar_output  *lar_input-l  [*lar_input-2])  [LISP  Function) 

WHERE.  The  arrays  are  similar  and  have  the  same  exponent,  and  larJnput-2  defaults  to 
lar^output. 

RETURNS:  Lar_output  after  its  elements  have  been  modified. 

SIDE  EFFECT:  Takes  the  minimum  of  each  element  of  lar_input-l  with  the  corresponding 
element  of  larJnput-2  and  stores  the  result  in  the  corresponding  element 
of  lar.output. 
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(minimum-filter  'lar.array  ’x^cliinension  x^widih)  [LISP  Function} 

liETl’HNS:  A  splice  o\  lar«arrav  is  returned  alter  the  lai_array  elements  are  modified  so 
that  the  slice  holds  the  desired  result.  The  size  of  the  given  dimension  for  the 
slice  is  x_\vidth-l  less  than  the  size  of  that  dimension  for  lar.array,  and  the 
slice  origin  is  0  for  that  dimension.  Other  dimensions  are  not  affected. 

SIDE  EFFECT:  Applies  a  filter  which  forms  the  minimum  of  the  last  x_width  input  values 
for  the  given  dimension  of  the  given  lar_array.  Thus  the  output  for  sub¬ 
script  j  in  the  given  dimension  is  the  minimum  of  the  input  for  subscripts 
j,  j-fl;  j-fx_\vidth-l. 

NOTE:  The  lar_array  element.'^  that  are  not  in  the  returned  slice  are  modified  in 
undefined  ways. 

BUCi:  Missing  values  are  not  handled. 

(multiply-array-elements  ’lar_out))ut  [LISP  Function] 

Mar_input-1  !’lar_inpnt-2') 

WHERE:  All  three  arrays  are  similar  and  lar_inpiit-2  defaults  to  lar_output. 

RETURNS:  Lar_outpiii  after  its  elements  have  been  set. 

SIDE  EFFECT:  Sets  each  element  in  lar^outpul  to  ihe  ))roduci  of  the  corresponding  ele¬ 
ments  in  the  two  inputs.  The  three  arrays  may  have  different  exponents. 

BUCi.  The  multiplication  is  done  using  modulo  arithmetic  in  event  of  overflow. 

(multiply-array-elements-by  dar_array  hi_multiplier)  [LISP  Function] 

RETURNS:  Lar_array  after  its  elements  have  been  modified. 

SIDE  EFFECT:  Multiplies  each  element  of  lar_array  by  n_multiplier. 

BUG:  The  multiplication  is  done  using  modulo  arithmetic  in  event  of  overflow. 

(overlay-missing  Mar^output  Mar^input)  [LISP  Function] 

WHERE:  Lar_output  and  larjnput  must  have  the  same  dimension  sizes  and  exponent. 
RETITIKS:  Lar_output  after  setting  some  of  its  elements. 

SIDE  EFFECT:  Replaces  every  missing  element  value  in  lar_output  by  the  corresponding 
element  value  in  lar_input. 

(power-array-elements  Mar_output  [’lar_input]  ’n_exponent)  (LISP  Function] 

WHERE:  Both  arrays  are  similar  and  larjnput  defaults  to  lar_output. 

RETURNS:  Lar^output  after  its  elements  have  been  set. 

SIDE  EFFECT:  Sets  each’  element  in  lar_output  to  the  n^exponent  power  of  the 
corresponding  element  in  larjnput.  The  two  arrays  may  have  different 
exponents. 


Printed  April  27,  1989 


BASIC  ARITHMETIC 


8-13 


(scalar-product  'ni_in|uii-l  ‘ai«inpiit-2)  [LISP  Function* 

WHERE:  The  two  ni  rnv'-  are  similar 

RETURNS:  A  number.  The  scalar  product  ol  tlie  two  arrays.  More  precisely,  the  sum  of 
the  products  ol’  corresponding  elements  in  the  arrays.  Nil  is  returned  if  either 
array  hu.'^  any  missing  values. 

(set-array-elements  'lar^arrny  ’upvalue) 

(set-array-elements  'Inr^array  tu'l) 

RETURNS:  Lar_nn  ay  after  its  elements  have  been  set. 

SIDE  EFFECT:  Sets  all  elements  of  lar^array  to  upvalue  or  nil 

(set-missing-to  'lar^array  ’n_vnluej 
RETURNS:  Lar_array  afici  setting  some  of  its  elements. 

SIDE  EFFECT:  Replac  es  every  mis^i^g  value  in  lar_array  by  n_value 

(shrink-missing  Tar_oui put  ’ai_inpni  *.\_countj)  [LISP  Function 

WHERE:  Lar_outpui  and  ar_injnit  have  the  same  exponent  and  the  same  dimension  size'- 
except  lor  the  X  and  dimensions  The  X  and  Y  dimensions  of  ar_inj)ui  are 
larger  by  2  than  ihe  X  and  ^  dimensions  of  lar_output.  X_count  defaults  to  2 
and  must  be  =  2 

RETlTtNS:  The  number  of  missing  values  left  in  lar_output. 

SIDE  EFFECT:  Copies  the  elements  of  ar_inpul  to  lar_output,  replacing  some  of  the  miss¬ 
ing  values  by  estimates.  In  general  the  output  element  equals  the  input 
element  unless  the  input  value  is  missing  and  has  at  least  x.count  non¬ 
missing  2-dimensional  8-neighbors. 

Missing  values  are  replaced  by  values  obtained  through  inspection  of  the 
2-dimensional  8-neighbors  of  the  missing  value. 

Given  a  pair  of  non-missing  neighbors,  the  missing  value  is  replaced  by 
their  average.  Generally  there  are  many  such  pairs,  from  which  one  is 
chosen  whose  two  values  are  closest  together.  If  there  are  many  closest 
pairs,  one  is  choosen  which  has  the  lest  bend  in  the  line  from  one  of  the 
pair  points  to  the  missing  value  point  to  the  other  pair  point. 


[LISP  F unct ion ’ 


[LISP  F unction’ 
[LISP  Function] 
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(shrink-missing-of  nrjnpm  jLISP  Fiinctionj 

’\_COUll(  ..  1 

WHERE.  More  than  one  x_couni  value  nia>*  be  given. 

RETURNS-  A  new  array  lar_oiiipui  w  liicli  is  computed  by  passing  arjnput  and  x_count 
through  .s//r ////.'- Prepnre-array  is  applied  to  ar.input. 

If  more  than  one  N.eouni  parameter  is  given,  each  x^couni.  parameter  is 
removed  from  the  parameter  list  as  it  is  used,  and  the  process  is  repeated 
with  the  lasi  lar_oiitpui  substituted  for  ar.input.  As  an  optimization,  the 
process  stops  when  there  are  no  missing  values  left  in  lar_output. 

(sin-array-elements  *lar_outpiii  *lai_ininn  )  (LISP  Function; 

WliERE;  Both  arrays  are  similar  and  Inrjnput  defaults  to  lar.output. 

RETURNS:  Lar_output  after  its  elements  have  been  set. 

SIDE  EFFECT:  Sets  eaeli  element  in  lar_output  to  the  sine  of  the  corresponding  element 
in  lrir_input.  The  two  arrays  may  have  different  exponents. 

(square-root-array-elements  lar_ouipui  ’lar_input])  [LISP  Function, 

WHERE.  Doth  array.s  are  similar  and  lar_input  defaults  to  lar_output. 

RETURN.'^:  Lar_outpui  after  its  elements  have  been  set. 

SIDE  EFFECT:  Sets  eaeh  element  in  lrir_output  to  the  square  root  of  the  corresponding 
element  in  lar_input.  The  two  arrays  may  have  different  exponents. 

(subtract-arrays  ’lar_output  [’lar_input-li  Tar_input-2)  [LISP  Function] 

WHERE:  The  arrays  are  similar  and  have  the  same  exponent,  and  lar_input-l  defaults  to 
Iar_output. 

RETURNS:  Lar_output  after  its  elements  have  been  modified, 

SIDE  EFFECT:  Subtracts  each  element  of  lar_input-2  from  the  corresponding  element  of 
lar_input-l  and  stores  the  result  in  the  corresponding  clement  of 
Iar_output. 

BUG:  The  subtraction  is  done  using  modulo  arithmetic  in  event  of  overflow. 

(sum-filter  Mar_array  ’x_dimension  *x_width)  (LISP  Function] 

RETURNS:  A  slice  of  lar_array  is  returned  after  the  Iar_array  elements  are  modified  so 
that  the  slice  holds  the  desired  result.  The  size  of  the  given  dimension  for  the 
slice  is  x_width-l  less  than  the  size  of  that  dimension  for  Iar_array,  and  the 
slice  origin  is  0  for  that  dimension.  Other  dimensions  arc  not  affected. 

SIDE  EFFECT:  Applies  a  filter  that  computes  the  mean  of  the  last  x^width  input  values 
for  the  given  dimension  of  the  given  Iar_array.  Thus  the  output  for  sub¬ 
script  j  in  the  given  dimension  is  the  mean  of  the  input  for  subscripts  j, 
j+l,  j-l-x_width-l. 

NOTE:  The  Iar_array  elements  that  are  not  in  the  returned  slice  are  modified  in 
undefined  ways. 
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Hrc:S:  Mi'-ing  values  are  not  linnclled  Overilow  is  liaiullecl  by  doing  modulo  arithmetic. 
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1.  GLOSSARY. 

(a-bitgraph-parameter-set  has-i'mt-u'idth  \\_line-\vidtli  (LISP  Macro] 

has- l-u'idth  'x_l-\vi(h li  ha^-l-hcight  *x_l-height 
has-5-u'idth  *x_5-\vidlli  ha$-5-hcight  ’x_5-height 
hns-IO-U'idfh  *x_lO-\vidih  has- lO-htight  ’x_lO-height) 

*  default- bitgraph-parameter-set*  |L1SP  Global  ariable] 

USE  A-lnf(ji  aj)h-parawcfer-f<ef  provides  parameters  for  drawing  bitgraphs  that  are 
dependent  upon  the  resolution  of  the  bitgraph.  E  g.,  such  parameters  as  would  be 
diflereni  for  a  1S00X1800  point  screen  and  for  a  ol2x*l80  screen 

* dtfauli-bitgrdjdi-parumettr-^et*  is  ll^ed  b\  bitgraph  functions  that  need  such 
parameters  as  the  default  bitgraph  parameter  set. 

MAS-LINE- WIDTH  Thi^  is  the  recoin  mended  minimum  line  width  in  pixels  for  drawing 
lines. 

MAS-l-WlDTH: 

HAS- 1-HEIGHT: 

MAS- 5- WIDTH 
HAS-5- HEIGHT: 

HAS- 10- WIDTH; 

HAS-lO-HEIGHT:  These  are  the  recommended  width  and  height  of  ruler  lines.  x_10-height 
and  x_l0-width  are  for  the  lines  that  mark  every  10  measurement  units. 
X_5-width  and  x_5-height  are  for  the  lines  between  these  that  mark 
every  5  measurement  uni  ts,  and  x_l-width  and  x_l-hcight  are  for  the 
other  lines  that  mark  every  1  measurement  unit.  Height  (but  not  width) 
may  be  0  to  eliminate  a  line. 
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(a-character-set  has’file  ‘s_lil<* 
has- font  ’s_font 
has-fitzea  \.\_xsize  ’x^ysize)) 

a-ch  aracter-set 
cset_ 

(read-character-set  *cset_charac  ter-s(M ) 

(has-file  ’cset_characler-set) 

(has-font  ’cset_characler-set) 

(has-sizes  ^csel_cliaracter-se( ) 
(has-x-range  ’cset^characier-sei) 
(has-y-range  ’csel_charncter-set) 
(has-width-range  ’cset_cliriracter-set ) 
(has-width-estimate  ’ci'Ct_c  liniacter-.sei ) 
(has-been-read  ’cseT_clinract(M-sel) 
(has-dispatch-array  ’cset_(  haracier-set) 
(has-bitgraph-array  'csct_cliarncier-sei ) 

USE:  .  A’Choracier’Set  clelino  the  bitgrnpli 
style  and  size. 


jSKETCH  Type  Macro^ 


[SKETCH  Type  Object] 
(Argument  Prefix] 

[SKETCH  Attribute  Macro] 

[SKETCH  Attribute  Macro] 
[SKETCH  Attribute  Macro] 
[SKETCH  Attribute  Macro] 
[SKETCH  Attribute  Macro] 
[SKETCH  Attribute  Macro] 
[SKETCH  Attribute  Macro] 
(SKETCH  Attribute  Macro] 
[SKETCH  Attribute  Macro] 
[SKETCH  Attribute  Macro] 
[SKETCH  Attribute  Macro] 

masks  of  a  character  set  with  a  particular 


The  character  set  is  delined  in  a  file  stored  in  the  format  of  the  Berkeley  UNIX  font 
library:  see  vfont(6).  This  file  is  read  into  memory  where  its  information  is  stored 
in  two  arrays:  the  dispatch  array  and  the  bitgraph  array.  Reading  the  file  and 
creating  the  arrays  is  not  done  until  the  function  rcad-charactcr-sct  is  applied  to 
the  character  set.  Until  then  the  character  set  attributes  not  set  when  the  charac¬ 
ter  set  is  created  are  vil. 

HAS-BEEN-READ: 

READ-CHARACTER- SET:  The  has-been-read  attribute  is  nil  if  the  character  set  has  not 

been  read  from  the  font  file  {has-file),  or  if  the  dispatch  and  bit- 
graph  array  elements  (see  HAS-DISPATCH-ARRAY  below)  are 
not  allocated.  This  latter  happens  when  the  character  set  is 
written  into  a  catalog  and  read  back  from  the  catalog  without 
allocating  the  elements  of  these  arrays. 

Otherwise  has-been-read  is  L 


The  function  call— 

(rca(/-c/iarac/cr-5c/  cset_character-set) 

reads  the  character  set  and  allocates  the  array  elements,  if  these 
have  not  already  been  done,  and  returns  the  character  set  as  its 
value  in  any  case.  This  function  call  is  usually  used  as  the  argu¬ 
ment  to  C  functions  requiring  the  character  set  after  it  has  been 
read. 
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H\S*S1ZES:  These  are  the  wicUh  (\_xsize)  and  height  (x.ysize)  in  pixels  between  charac- 
UMs,  For  a  character  set  witli  variable  width  characters,  the  widtli  may  not 
be  the  maxmuint  width  of  any  character,  but  should  be  the  maximum  likely 
average  width  of  the  characters  in  any  set  of  English  words  containing  at 
least  5  characters  (including  spaces). 

X_xsize  delaulis  to  the  value  of  the  lia^-undth-e^fimafe  attribute,  while 
.\_ysize  defaults  to  the  ceiling  of  has-y-raiige  maximum  minus  the  has-y- 
ranye  minimum  times  1.2. 

RAS-X-RANGE: 

R\S-V-RANGE: 

RAS-WIDTH-RaNGE.  These  are  lists  of  the  form  ’(x^mmimum  x^maximiim)  giving  the 
smallest  and  largest  X  and  Y  coordinates  of  any  pixel  in  any  charac¬ 
ter  of  the  character  set;  and  giving  the  smallest  and  largest  width  of 
any  character  in  the  character  set.  The  width  of  a  character  is  the 
number  of  pixels  the  cursor  is  to  be  moved  to  the  right  when  the 
character  is  drawn  (and  has  nothing  to  do  with  how  many  pixels  the 
character  turns  on) 

RASAVIDTH-ES'TIXLATE:  This  rs  the  width  of  the  w’idest  capital  letter  other  than  M  or  W 

It  may  be  used  to  estimate  the  horizontal  size  of  the  character 
set. 

RA$-FO.\T:  A  symbol  naming  the  font.  Some  of  the  fonts  available  and  their  has-sizes 


Printed  April  27,  1989 


BIT  GRAPHICS  9-4 

Font  Has-Sizes 


filed-  rowan 

(9  H).  (12  21),  (10  27).  (19  32).  (25  .12) 

her^hey-bold 

113  19).  (15  21).  (18  25),  (20  28).  (22  31),  {24  34),  (26  36). 
(31  42l.  (35  49).  (40  54),  (44  59).  (48  66),  (53  72),  (61  83). 
(79  107) 

hershey-iialic 

(13  19).  (1-5  21).  (18  25),  (20  27),  (22  31),  (24  33),  (26  36), 
(31  41).  (35  48).  (40  54).  (44  59),  (48  66),  (53  71),  (61  82), 
(79  105) 

hershey-rowan 

(13  19).  (15  21).  (18  25),  (20  28).  (22  34),  (24  34),  (26  36), 
(31  42),  (35  49).  (40  54),  (4  1  59).  (48  66),  (53  72),  (61  83), 
(79  107) 

notnt-bold 

(17  27),  (21  32).  (24  37) 

no  me-  ttalic 

(10  27).  (21  321.  (24  37) 

nmuK-rowan 

(10  27).  (^O  32).  (23  37) 

screen-hold 

(8  15).  (9  17) 

screen-roman 

(6  9).  (7  12).  (7  15).  (8  17),  (8  17) 

script 

(51  51) 

serif-roman 

(7  13),  (7  14),  (7  15),  (8  17),  (9  19) 

sliadoir 

(31  42) 

iiwes-bold 

(13  16),  (15  19),  (17  24),  (19  26),  (22  29),  (24  3l),  (26  34), 
(30  39),  (35  45),  (39  50),  (43  55),  (48  61),  (52  68),  (60  78), 
(78  100) 

times-italic 

(12  17),  (14  19),  (16  23),  (18  25),  (20  28),  (22  32),  (24  34), 
(28  39),  (32  45),  (36  50),  (40  56),  (44  61),  (48  67),  (56  77), 
(72  99) 

tinies-roman 

(14  19),  (16  23),  (18  26),  (20  28),  (23  32),  (25  35),  (27  37), 
(32  45),  (36  50),  (41  56),  (45  62),  (50  69),  (54  74),  (63  88), 
(81  112) 

If  a-choracier-set  has  non-n?7font  and  lias-sizes  it  is  enterred  in  the  font  data 
base  maintained  for  use  by  the  find- character- set  function.  See  the  descrip)- 
tion  of  that  function. 
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R^ij-FJLE:  The  I’NIX  loiii  lilv  (''t  e  vl‘ont(o)  for  lormal).  Tins  file  is  searched  for  using  the 
directory  lisi  pr^'Vidfd  ly\  — 

(slalu^  Jonl-search-path). 


(bar-graph  *bgar_oiii pm  ‘Irn.iiipnt  ruLrulor  [LISP  Function] 

I  s.mode  ! 

WHERE  The  X  dimension  size  of  l>gar_oulpiil  must  be  the  X  dimension  size  of  lar_inpiil 
times  some  integer  \_\Nidili  0. 

S_mode  must  be  either  (Iran.  err/6e.  reverse,  or  invisible:  the  default  is  draw 

SIDE  EFFECT  Logically  OR  s  (if  s_niode  is  draw)  a  bar  graph  of  lar_inpiit  into 
lar^outpui.  I'he  bars  run  vertically  (in  the  Y  dimension)  upward  (toward 
negative  ''i  \alue>)  for  some  bar  height  chosen  by  the  associated  Iar_inpnt 
element  value  "Jdie  height  of  the  bar  is  determined  by  mapping  the  ele- 
meni  value  by  ilic  inverse  of  the  affine  transformation  defined  by 
niLrulei .  and  ro////(/*ing  the  result  to  the  nearest  integer.  Bars  with  nega¬ 
tive  height  are  not  drawn,  and  bars  with  height  larger  than  the  dimen¬ 
sion  sizr  of  bgai_' >111  put  are  clipped  to  that  Y  dimension  size. 

Thv  wnlth  ol  «  .uh  bar  m  the  X  direction  is  \_width. 

Missing  cleinenis  ol  lar_inpin  do  not  produce  a  bar 

(bar-graph-of 'ar_input  N_licighi  N_widih^)  [LISP  Function] 

WHERE:  X^height  >  0.  \_width  >  0.  X_width  defaults  to  1. 

Lar_input  must  be  one  dimensional. 

RETURNS:  A  new  bitgraph  array  bgar_output  whose  elements  are  set  by  passing  it  to 
bar-graph.  Bgar_output  has  X  dimension  size  equal  to  x_width  times  the  X 
dimension  size  of  ar_input.  Bgar_output  has  Y  dimension  size  equal  to 
x_height . 

If  ar_input's  X  dimension  has  a  ruler,  the  ruler  for  bgar_output’s  X  dimen¬ 
sion  is  set  to  the  ruler  of  ar_input’s  X  dimension  with  the  scale  multiplied  by 
x_width. 

If  ar_input  has  any  non-missing  element,  the  ruler  for  bgar^output’s  Y 
dimension  is  set  to— 

(x^height  (0  x_maximum+l)) 

where  x_maximum  is  the  maximum  value  of  any  ar^input  clement.  This 
ruler  is  also  passed  to  bar-graph. 
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(bitgraph-box  bgar_output  'n_xminimuni  'n«-\ma\imum  jLiSP  Function* 

n.yminimuni  n.ymaximiim  "s.niodej) 

WPIERE:  The  liniiis  n_xminimum  and  n.xmaximuni  may  be  exchanged  without  effect, 
and  similarly  n.yminimum  and  n.ymaximum. 


S_mode  must  be  either  dratr,  erase,  reverse,  or  invisible:  the  default  is  draw. 
RETURNS:  Bitgraph-bor  returns  bgar_output  after  setting  some  of  its  bits. 

SIDE  EFFECT:  Logically  OR’s  (if  s_mode  is  draw)  a  rectanglular  box  with  horizontal  and 
vertical  sides  given  by  the  lines— 

X  ==  {ceiling  n_xminimum) 

X  ==  (floor  n_xmaximum) 

Y  ==  (ceiling  n_yminimum) 

^  ==  {floor  n_yniaximum) 

into  bgar_outpul. 

.NOTE'  {has-ln}€-u'idth  ^default-bitgraph-parawefer-set*) 


i.*^  a  good  minimum  value  for 

n_\maximiini  -  n_xmininuim  -f  1 
or 

n_ymaximiim  -  n_yminimum  1 

when  the  purpose  is  to  draw  a  line  that  bounds  an  image,  graph,  table,  or  other 
figure. 

(bitgraph-Iine  ’bgar^output  'n_xl  ’n_yl  'n_x2  *n_y2  [LISP  Function] 

['n_width  [’s_mode]|) 

WHERE:  N_width  may  be  nil  to  mean  the  same  thing  as  a  missing  n_width  argument. 


S_mode  must  be  either  draw,  erase,  reverse,  or  invisible:  the  default  is  draw. 
RETURNS:  Bgar_output  after  setting  some  of  its  bits. 

SIDE  EFFECT:  Draws  the  line  joining  the  point  (xl,  yl),  and  the  point  (x2,  y2),  by  logi¬ 
cally  OR'ing  (is  s_mode  is  draw)  a  parallelogram  containing  that  line  into 
bgar_output. 

The  parallelogram  starts  at  the  point 

(xl  —  xw/2  —  yw/2,  yl  —  yw/2  +  xw/2) 

and  has  sides 

(x2  —  xl  -h  xw,  y2  —  yl  +  yw) 

and 

(yw,  -  xw) 

where 
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length  =scirt  ((x2  +  (y2  -yl)**2) 

xw  =  n«^Yidtll  *  {n2  —  xl )  -  length 
y\v  =  n^widlli  (y2  —  yl)  .  length 

If  n_widtli  is  nil,  then  x\y  and  y\\  are  computed  as  above  and  then 
transformed  by— 

m  =  (1  +  2"'*^)  *  max  (lx\v|.  lywj) 
xw  =  m  *  xw 
y\y  =  m  *  yw 

which  gives  the  smallest  effective  width  that  will  draw  a  visible  line. 

In  order  to  ensure  that  the  line  is  drawn  exactly  the  same  way,  no  matter 
how  it  is  presented,  and  in  spite  of  rounding  errors,  the  end  points  are  first 
exchanged  unless  x2  >  xl  or  x2  ==  xl  and  y2  >  yl. 

Before  the  parallelogram  is  dra^Yn.  the  line  is  clipped  so  that  xl  and  \2  lie 
in  approximately  the  range 

(-0  87-1  -h(lxw|  -f  lyw|)/2.  xsize  —  0  12G  —  (Ixwl  -fly\vj)/2) 
and  yl  and  y2  lie  in  approximately  the  range 

(—0.87^1  -f  (Ixwl  -}-lyw|)/2.  ysize  —0.126  —  (L\\v|  -}“lyw|)/2) 

The  order  of  operations  is  thus— 

exchange  of  end  points  if  necessary 
clipping 

specification  of  parallelogram 
OR’ing  of  parallelogram 

(bitgraph-lines  ’bgar.output  [n_dot-size]  [s_mode]  [LISP  Function] 

\has~origins  ’(n_xorigin  n_yorigin)| 

(/las- zooms  *(n_xzoom  n_yzoom)| 

P(n_x  n_y)  ...]  [nil]  [’ar_array  ...j) 

WHERE;  N_dot-size,  n^xzoom,  and  n^yzoom  default  to  1,  while  n^xorigin  and  n^yorigin 
default  to  0. 

S_mode  must  be  either  draw,  erase,  reverse,  or  invisible:  the  default  is  draw. 
RETURNS:  Bgar^output  after  modifying  it. 

SIDE  EFFECT:  Logically  OR’s  (if  s_mode  is  draw)  into  bgar.output  lines  whose  end 
points  are  given  by  arguments  of  the  form  ’(n_x  n_y)  or  ar.array.  For 
ar^array  arguments,  each  row'  of  the  array  represents  a  point,  with  the 
first  column  (X  subscript  equal  0)  being  the  point’s  X  coordinate,  and  the 
second  column  (X  subscript  equal  1)  being  the  point’s  Y  coordinate.  The 
array  must  have  exactly  tw'o  columns  (array’s  X  dimension  size). 

Point  arguments  may  also  be  missing:  these  are  represented  by  nil 
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argnmeius.  or  bv  array  rows^  whose  elements  are  missing.  The  missing 
poiius  break  ihe  s^ecjiience  ol'  all  points  into  subsequences  of  non-missing 
poims.  Each  such  subsequence  defines  a  broken  line  obtained  by  conneci- 
ing  ;he  subsecjueiice  points  in  order.  It  is  these  broken  lines  that  are  logi¬ 
cally  OR’ed  (if  s_mode  is  draw)  into  bgar_output. 

The  lines  are  drawn  by  moving  a  circular  dot  whose  size  in  pixels  is 
n_dot-sizc. 

{bitgraph-parallelogram  ’bgar_oinput  hi_y  ’n_xl  ’n_yl  [LISP  Function] 

'n_x’2  ’n_y2  ['s_mocle]) 

WHERE:  S_mode  must  be  either  dratr.  erase,  reverse,  or  invisible:  the  default  is  draw. 
RETURNS:  Bgar^outpui  after  selling  some  of  its  bits. 

SIDE  EFFECT:  Logically  OR‘s  (is  s_mo(le  is  draw)  a  parallelogram  into  bgar_output.  The 
side.*^  me  formed  by  the  vectors  (n_xl  n_y2)  and  (n_x2  n_y2)  drawn  from 
the  origin  (n_\  n_y).  .All  the  coordinates  may  be  given  as  fractions. 

Only  one  boundary  in  each  direction  has  the  property  that  points  exactly 
on  ii  are  turned  on.  The  other  boundary  in  the  direction  has  the  properly 
that  point'-  exactly  on  it  are  turned  off. 

It  may  be  wise  to  use  fractional  coordinates  to  be  sure  the  right  things  are 
turned  on:  e.g.- 

{hitgraph-parallelogram  bgar_output  -0.5  -0.5  0.5  -0.5  21  21) 

wmH  draw  a  20  point  line  at  a  45  degree  angle  from  (0  0). 

In  order  to  ensure  that  the  parallelogram  is  drawn  exactly  the  same  way, 
no  matter  how  it  is  presented,  and  in  spite  of  rounding  errors,  transforma¬ 
tions  are  made  on  the  parameters  to  put  them  in  cannonical  form  (for 
instance,  x  y  is  changed  to  the  leftmost  point  of  the  parallelogram  in  the 
case  where  bgar_output  has  yincrement  =  1). 

A  parallelogram  any  part  of  which  lies  outside  the  X  and  Y  coordinate 
ranges- 

(-0.875,  xsize  -  0.125)  (-0.875,  ysize  -  0.125) 
wdll  not  be  draw*n. 
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(bitgraph-ruler  bgar^output  ruLruler  [LISP  Function] 

’N_\ni illinium  ’x_\ma.\iiiiiini  ’x_vba.se 
s_mode 

(lo'revcrsc  g_reverse-s^\  itch; 

has-bilgraph-paraineier-iiei  ’bgps_parameter-set)) 

WHERE:  X_xin iiiini iim  may  be  above  x_xmaximum. 

The  i  iiLruler  scale  must  be  non-zero. 

Bgar_oiitput  must  have  either  xincrement  or  yincrement  equal  to  1  or  -1. 

The  clerault  value  of  bgps_parameter-set  is  *defaiilf-bi{graph-para7}}eicr-s€i*. 
Bgp.>_paranietei-set  contributes  the  parameters  x_l-height.  x_l-\\idth.  x_-> 
heighi.  x_5-wi(lth.  x_lO-lieighl ,  x_10width. 

11  g_ievcrse-s\\  iicli  is  nou-tnl  the  signs  of  x_l-height,  x_5-height.  and  x_10 
height  are  eflectively  changed. 

S_inode  iniisi  be  either  drair.  erase,  reverse,  or  invisible:  the  default  is  draic 
RETURNS;  Rater  returns  bgar_oiitput  after  setting  some  of  its  bits 

.SIDE  EFFECT:  B/lgraph-raler  makes  ruler  marks  in  bgar_output  with  the  marks  ha\  iiig  a 
base  on  ilie  horizontal  (X  direction)  line  defined  by  x_xminimum, 
.\_xmaxinium,  and  x_ybase.  The  marks  themselves  run  in  the  Y  direction. 

The  X  coordinate  is  scaled  so  that  unsealed  coordinate  x_x  is  mapped  first 
onto  x_x— x_minimum  and  then  by  ruLruler  to  a  real  number  called  the 
scaled  X  coordinate.  Marks  are  placed  at  scaled  X  coordinates  -2,  -1, 
0.  1,  2,  ...  .  Marks  at  ...,  -20,  -10,  0,  10,  20,  ...  are  of  (Y  coordinate) 
height  x_l0-height  and  (unsealed  X  coordinate)  width  x_10-width.  Marks 
at  ...,  -15,  -5,  5,  15,  ...  have  height  x_5-height  and  width  x_5-width.  The 
rest  of  the  marks  have  height  x_l-height  and  width  x_l-width. 

If  possible  the  ruler  scale  is  multiplied  by  10  repeatedly  (without  changing 
the  value  x_minimum  maps  onto)  until  doing  so  further  would  cause  the 
marks  to  overlap.  If  necessary  the  ruler  scale  is  divided  by  10  repeatedly 
until  none  of  the  marks  overlap.  In  order  not  to  overlap,  marks  are 
required  to  have  x_l-width  space  between  them. 

Marks  can  be  surpressed  by  setting  the  appropriate  heights  to  0.  However 
the  widths  may  not  be  0,  and  the  scale  will  still  be  choosen  as  if  the  marks 
were  being  made. 

If  the  heights  are  positive  the  marks  are  made  in  the  positive  Y  coordinate 
direction,  which  is  down.  If  the  heights  are  negative  the  marks  will  be 
made  in  the  opposite  direction,  up.  The  variable  width  marks  are  cen¬ 
tered  on  their  nominal  X  position.  A  mark  is  not  made  if  any  part  of  it 
would  be  outside  the  limits  of  bgar_output. 
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(bitgraph-text  'iibar^outpiit  ’(x^xorigin  x.yorigm)  [LISP  Function] 

'>_nio(lo  .’s_oriciuation  ’s^ndjiisi  'ci^ci_cliaracter-5ei 
^  t_>trii)g  ...) 

WHERE.  S_mo(lc  </n/(r{tlic  (Ivl’niili).  erase,  rerer.^e,  or  ivnsible. 

S_orieiM  :ii  ion  is  }nirrov.  Uft-roiatc.  left-mirror,  top-rotate,  top-inirror,  right- 
rotate.  or  right-mirror. 

S_n(ljusi  i.'?  left,  right,  orcr.  or  under. 

Nil's  in  the  optinal  part  of  the  argument  list  are  ignored. 

SIDE  EFFECT  Text  is  drawn  at  the  iiulieaiecl  origin. 

Each  t_string  argument  is  taken  to  be  one  or  more  separate  lines  of  text. 
Only  printing  characters,  the  single  space  character,  the  tab  character, 
and  the  line  feed  charncier  are  permit  led  in  the  strings.  Tab  stops  are  set 
every  S  characters  from  the  l)eginning  of  each  string,  or  from  the  previous 
line  ferd  character.  Tabs  arc  translated  into  space  characters. 

The  width  and  height  of  the  total  text  consisting  of  all  the  lines  is  com- 
))uied.  'J'hi.s  is  ii’^cd  to  form  an  imaginary  box  around  the  text.  The  text 
line<  are  then  adjusted  iii  the  box  according  t-o  some  of  the  s^adjust 
parameters.  Lastly,  ihe  box  is  positioned  m  the  ubar_output  according  to 
the  origin  position,  s^adjust  i^arameters,  and  s.orientation  parameter, 
and  the  text  is  drawn. 

Individual  characters  tliat  will  not  fit  completely  inside  ubar_output  are 
not  drawn.  Characters  tliat  will  fit  completely  inside  are  always  drawn. 

S^ADJUST:  The  s_adjust  parameters  control  the  positioning  of  lines  within  the  text  box, 
and  the  positioning  of  the  box  relative  to  the  origin.  The  possible  s.adjust 
values  are— 
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S.ORIENTATION: 


left 

Tlir  ongiii  is  plncccl  just  to  the  left  of  the 
ho\ 

Tilt*  hues  of  le.xi  with  the  least  amount  of 
bhuik  space  at  their  left  are  left  justified  in 
tlu-  bo.\  The  lines  with  the  next  least 
niiiouni  of  blank  space  at  their  left  have 
tlicii  lirst  non-blank  character  printed 
directly  under  the  character  in  the  same 
column  of  the  first  line  above  them  that  has 
already  been  justified,  if  any,  or  the  first  line 
belo\\  them  if  there  is  no  such  line  above. 
.And  so  forth,  until  all  lines  are  justified. 

right 

Like  left  but  to  the  right  instead  of  the  left. 

If  licit Ikm*  left  or  right  is  given,  each  line  has 
blank  space  at  its  beginning  and  ending  re¬ 
moved.  and  is  then  centered  in  the  box.  The 
origin  IS  placed  at  the  center  of  the  box  in 
the  horizontal  dimension. 

under 

Tlic  oricin  is  placed  just  under  the  box. 

over 

Tlic  origin  is  placed  just  over  the  box. 

If  neiihci  under  or  over  is  given,  the  origin  is 
placed  at  the  center  of  the  box  in  the  verti¬ 
cal  dimension. 

This  is  one  of  the  values— 

mirror 
Ufi-mirror 
top-mirror 
right-mirror 


nil 

left-rotate 

top-rotate 

right-rotate 


The  entire  text  is  rotated  as  indicated  around  the  origin  position.  Nil 
means  to  do  no  rotation;  top-rotate  means  to  rotate  180  degrees  to 
make  the  bottommost  part  of  the  characters  nearest  the  top  of  the 
display.  The  mirror  forms  do  not  cause  the  characters  to  be  mirror- 
imaged,  nor  do  they  reverse  the  order  of  the  characters  in  the  text. 
But  they  do  switch  which  side  of  the  text  the  origin  is  on,  left  or  right, 
when  viewed  after  any  rotation. 
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(find-character-set  sjont  (n^xsize  n_ysize)) 


jLlSP  Function, 


(clear-ch  aracter-sets  s^lon  i  j ) 
’•‘find-character-set* 
*character-set- fonts* 


[LISP  Global  Variable] 
[LISP  Global  Variable] 


[LISP  Functionj 


WHERE:  *fin(l‘characfer‘set*  has  the  default  value  ^sbg/^bg_. 

RETURNS:  Fuul-characfer-sef  returns  a-characitr-sti  with  the  given  has-fonf  attribute 


and  the  largest  attributes  available  that  are  less  than  or  equal  to  the 

given  sizes. 

If  there  are  no  character  sets  with  the  given  lias-font  attribute,  the  catalog  file 
with  the  name— 

{coucaf  *fin(l-cliaracter’Sef*s^{oTi\  \ca) 
is  read.  It  will  presumably  have  character  sets  with  s^font  as  their  has-font. 

Clear-characfer-sefs  clears  the  font  data  base  of  all  character  sets  with  a 
given  has-font.  or  all  character  sets  if  no  argument  is  given.  *characttr-sct- 
fout.>^  i.s  a  list  of  all  the  fonts  in  the  font  data  base. 


ILISP  Function’ 


(get-character-bitgraph  cset_characier-set  's/x^character 

-*s_orientationj) 


USE  ONLY  WHEN:  Diagnosing  character  set  appearance. 

WHERE:  S_orientation  is  nil,  mirror,  left-rotate,  or  right-mirror. 

RETURNS:  The  bilgraph  array  of  a  character  in  cset_character-set.  The  character  is  the 


first  character  of  s_character,  or  has  the  ASCII  code  x_character. 

The  array  presents  the  character  in  the  given  orientation;  ni7  for  normal,  mir¬ 
ror  for  mirror  image,  left-rotate  for  the  rotated  90  degrees  to  the  left,  and 
right-mirror  for  the  mirrored  character  rotated  90  degrees  to  the  right.  In  all 
these  cases  the  Y  dimension  increment  equals  1,  so  the  four  orientations  actu¬ 
ally  select  four  different  arrays  in  memory. 


(LISP  Function] 


(get-character-dLsplay  ’cset^character-set  ’s/x_character) 


USE  ONLY  WHEN:  Diagnosing  character  set  appearence. 

RETURNS:  The  a-bitgraph- character  descriptor  for  a  character  in  cset_character-set. 


The  character  is  the  first  character  of  s_character,  or  has  the  ASCII  code 
x^character. 


’ 'rioted  April  27,  1989 


BIT  GRAPHICS 

9-13 

sbg^bit  x_x’ 

[C  Macro] 

sbg_tobit  jx_.\ 

[C  Macro; 

sbg_frombit  [\_x 

[C  Macro 

sbg^shift  jx_xj 

[C  Macro] 

sbg_endbit 

[C  Macro] 

sbg_endtobit 

[C  Macro] 

sbg_endfrombit 

[C  MacrOj 
[C  Macro) 

sbg_endshift 

WHERE.  0  <  =  x_.\  <  =  31 . 

REQUIRES;  ^include  <sbg ''sbg_bit.h> 

RETUR.NS  The  subscripted  expressions  return  a 

xihng  which,  when  viewed  as  a  one 

dimensional  32  bit  array  with  xincrement  ==  1,  has  bit  x_x  only  on  in  the 
case  of  sbg_hit.  has  only  bits  0.  1,  ....  n_x  on  in  the  case  of  sbg^tobit,  or  has 
only  bits  x_x,  ....  31  on  in  the  case  of  sbg^roinbit. 


In  the  case  of  ^bg^shijt  bits  ...,  7  are  on  within  each  of  the  4  bytes  within 
the  array:  this  is  useful  for  right-to-left  computers  for  masking  a  word  in 
whicli  every  byte  is  to  be  right  shifted  by  \_x.  The  mask  for  a  word  in  which 
each  byte  is  to  be  left  shifted  by  x_x  should  be 

'  f^bfuahi/l  'S  -  N_\j 

for  1  <  =  .\_.\  <  =  8. 

sbg^bit.  sbg^tobit,  sbg^rombit,  and  sbg^shift  are  contiguous  vectors  of  ulong's, 
which  may  be  stepped  along  by  a  viong  pointer  p  using  a  *  p  -h- h  expression. 
The  expressions  shg^eiidbit^  sbg^ciidiobii,  sbg^cndfrombit,  and  sbg^cndshijt  are 
pointers  to  ulovg's  that  point  at  the  first  location  after  the  respective  vectors, 
so  expressions  such  as  p  <  sbg^eiidbit  may  be  used  to  terminate  loops. 

sbg^box  (bgar_output,  x_xmin,  x_xmax,  x_ymin,  x_ymax,  g_mode)  [C  Function] 

WHERE:  G_mode  must  be  one  of  SBG^RAW\  SBGJIRASE,  SBGJtEVERSE,  or 
SBGJNVISIBLE. 

SIDE  EFFECT:  Draws  a  box  in  bgar_output  with  the  given  minimum  and  maximum  X 
and  Y  coordinates. 

NOTE:  X^xmin  and  x_xmax  may  be  reverse  (x_xmin  greater  than  x^xmax)  without 
effecting  results  (the  function  sorts  these  arguments).  Similarly  for  x^ymin  and 
x_ymax.  If  the  box  is  too  big  to  fit  in  bgar^output,  the  box  is  clipped. 
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sbg_character 

bgchar_ 

bgchar_character—>sbg_coffset 
bgchar_character— >sbg_corigin  .x^dimcnsioir 
bg(har_character— >sbg_csize  :\_(limenMOii 
bgchar«characler—>sbg_c  width 


ICType: 
[Argument  Prefix 
[C  Structure  Element 
[C  Structure  Element^ 
[C  Structure  Element^ 
[C  Structure  Element' 


a-bitgraph-character 

an-allocate-bitgraph-character 

SBG^CHARACTER 


[SKETCH  Type  Object! 
[SKETCH  Type  Object  j 
jC  Global  Variable' 

USE:  This  is  an  element  in  the  clispiitch  array  of  a  character  set.  It  gives  information 
about  one  character.  The  is  the  index  of  the  first  long  of  the  character’s 

a-vhit  matrix  within  the  character  set’s  bitgraph  array.  This  matrix  has 
sbg^csizelSAR^l  columns  (X  size)  and  .^bg^csize\SAR^Y\  rows  (Y  size).  Each  row. 
however,  is  expanded  to  on  integral  number  of  long's  by  adding  0  bits  on  the  end. 
so  the  actual  number  of  column^s  is— 

((•s^r/_r6/re  .S’4/?_A*J  -l-3l)/32)*32 


The  character’s  bitgiuph  matiix  is  to  be  inserted  in  output  at  some  displacement 
from  the  cursor  location.  Thi>  displacement  is  is  given  by  shg^corigin\SAR^'^i  in 
the  X  direction  and  sb(j_corigin  SAR_)'  in  the  direction. 

After  inserting  the  character,  the  cursor  is  to  be  moved  sbg^cwidth  columns  to  the 
right. 

A-BITGRAPH-CR^ACTER: 

AN-ALLOCATE-BITGRAPH-CHARACTER: 

SBG_ACHAFIACTER :  A-bitgraph- character  is  the  SKETCH  type  of  a  sbg^characier  object. 

It  is  formally  a  pointer  to  a  structure.  An- alio  cate- bit  graph- 
character  is  the  SKETCH  type  used  as  an  array  has- element- type  if 
the  bitgraph  character  structures  are  to  be  the  array  elements.  It 
refers  to  the  structure  proper,  and  not  a  pointer  to  it. 
SBG^CHARACTER  is  the  C  global  variable  equal  to  an-allocate- 
bitgraph- character. 

sbg_dot  (ux_ubbase,  x^xincrement,  x_y increment,  [C  Function] 

x^xoffset,  x^yoffset,  x^xdelta,  x_ydelta,  x«size,  sjnode) 

WHERE:  An  output  a-ubit  array  is  located  at  base  bit  address  ux_ubbasc  and  has  incre¬ 
ments  x_xincrement  and  y_yincrement. 

X_xoffset,  x_yoffset,  x_xdelta,  x_ydelta,  and  x«size  are  all  measured  in  units  of 
1/2  pixel.  X_xdelta  and  x_ydelta  must  be  in  the  range  from  -2  through  +2. 
X_size  must  be  in  the  range  from  2  to  28  and  have  been  previously  initialized 
by  initialize-bitgraph-point-size. 

S^mode  is  SBG.DRAW,  SBG_ER-\SE,  SBG  JIEVERSE,  or  SBG JNVISIBLE. 
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Eiilicr  N_\incremeni  must  equal  1,  or  \«xincremeni  and  x_yincremeni  must 
both  be  exactly  divisible  by  S. 

SIDE  EFFECT:  A  dot  is  put  into  ihe  output  array  all  along  the  straight  line  from  the 
position  — 

(\_xoffset-hepsilon  x^yoflseH-epsilon). 

to  the  position 

(x_xoffset-hx_xdelta-hepsilon  x_yoffset-l-x_ydeUa-hepsilon), 

where  these  offset  and  delta  coordinates  are  in  units  of  1/2'ih  pixel:  i.e., 
have  2  times  the  resolution  of  the  X  and  Y  coordinates  in  the  output 
array.  The  diameter  of  the  dot  is  x_size,  also  in  1  /2*tli  pixel  units 

Epsilon  is  ehoosen  to  be  a  very  small  number,  e.g.  0.001.  It  prevents 
anomalies  such  as  some  vertical  lines  with  size  =  2  being  twice  as  wide  as 
others. 

If  s_mode  is  SBG_DR.A\V  the  dot  pixels  are  set  to  1;  if  SBG^ERASE.  the 
pixels  are  set  to  0;  if  SBG_REVERSE,  the  i^ixels  are  complemented:  and  if 
SBCi_l.N\*lSlBLE.  the  pixels  are  left  untouched. 

\v.\F.\IXC  .Xo  check  is  made  to  see  if  the  dot  will  gq  off  the  edge  of  the  array.  Memory 
may  be  damaged  if  it  does. 

No  check  is  made  to  see  if  the  arguments  are  in  their  proper  ranges. 

sbg_line  (bgar_outpui,  x_xl,  x_yl,  x_x2,  x_y2,  x_width,  g_mode)  (C  Function] 

WHERE:  X_xl,  .x_yl,  x_x2,  x_y2,  and  x_width  are  all  in  units  of  2**-16,  and  x^width 
may  equal  SAT^MISSING  to  represent  a  nil  or  missing  value. 

G_mode  must  be  one  of  SBG^RA\\\  SBGJERASE,  SBG^EVERSE,  or 
SBGJNVISIBLE. 

SIDE  EFFECT:  Performs  the  same  action  as  the  LISP  function  call  — 

{bitgrapli-line  xl  yl  x2  y2  width) 

where  the  LISP  arguments  are  the  floating  p>oint  equivalents  of  the  C 
arguments. 
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sbg_or  (ux«outp.  x.oinc.  *ul.\.inp.  x^xsize,  x.ysize)  jC  Function] 

rSE  ONLY  WHEN:  Maininining  the  SKETCH  biigraph  package.  Others  may  use  this 
function,  but  must  beware  that  no  error  checking  whatever  is  clone  by 
the  function. 

WHERE  .An  output  a-ubif  array  is  located  at  bit.  address  ux_outp  (as  for  sar.ubbase), 
and  an  input  a-vbif  army  at  addres.«  *iilx_inp.  The  xincrement  of  both  arrays 
must  be  1.  the  yincrement  must  be  \_oinc  for  the  output  array  and  32*x_xsize 
for  the  input  array,  the  .vsize  must  be  32*x_xsize  for  both  arrays,  and  the  ysize 
must  be  x_ysize  for  both  arrays. 

SIDE  EFFECT:  Logically  OR's  the  input  array  into  the  output  array.  Is  designed  as  a 
high  speed  function  used  as  a  primitive  function  in  the  bitgraph  package 
for  01  ing  characters,  pixel  shades,  contours,  etc  into  a-ubif  arrays. 

BUG:  The  current  code  will  not  work  on  a  right  to  left  computer  (in  the  tradition  of 
WAX  and  l.XTEL.  not  IBM  or  MOTOROLA)  unless  uloiigs  do  not  have  to  be 
aligned  (which  they  do  not  on  a  WAX) 

sbg_pgram  (bgai_output.  x_x.  x_y.  x_\L  .\_yl.  .\_x2:  x_y2,  g_mode)  jC  Function] 

\VHERL:  X_x.  x_y.  x_xl.  x_yl.  x_\T.  and  x_yl  are  all  in  units  of 

G_modr  must  be  one  ol  SBC^DHAW',  SBG^ERASE,  SBG^REVERSE,  or 
SBGJ.WISWLE. 

SIDE  EFFECT:  Same  as  the  LISP  function  — 

{bifgraph-paralleloffraw  output  x  y  xl  yl  x2  y2) 

sbg_ruler  (bgar_out put.  f_xfirst..  f_X5tep.  [C  Function] 

.\_xminimum,  \_xma.vimum.  \_ybase,  x_lwidth,  x_lheight, 
x_5wiclth,  x_5height,  x.lOwidth,  x_lOheight,  g_mode) 

WHERE:  X^xminimum  may  be  above  x_xmaximum. 

GWmode  must  be  one  of  SBG^RAW,  SBG^ERASEj  SBC^EVERSE^  or 
SBGjyVlSIBLE. 

SIDE  EFFECT:  Performs  same  action  on  bgar.output  as  the  LISP  function  call— 

{bitgraph-rulcr  output  ’((0  ...)  (f_xfirst  ...)  f_xstcp)  xminimuin  xroaximum  ybase  mode 
{a-b\tgrapli-para7iieicr-$ct  ha$-l-wtdth  1-width 

has-  1-htighi  1-height 
has-5-width  5-width 
has-5-height  5-height 
has-lO-width  10-width 
has-lO-hcighi  10-hcight)) 
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sbg_s_or  {ux_outp.  x_oiiK  .  ’ii'^x_inp.  x_xsize.  \_ysize)  [C  Function- 

USE  ONLY  WHEN:  Mainioiniiig*  ihv  SKETCH  biigrapli  package.  Others  may  use  this 
runction.  but  niu'^i  beware  that  no  error  checking  whatever  is  done  by 
the  function 

WHERE:  An  output  a^uhii  array  is  located  at  bit  address  ux^outp  (as  for  sar^ubbase), 
and  an  input  o^ubll  arrav  at  address  *usx_inp.  The  xincrement  of  both  arrays 
must  be  1;  the  yincrement  must  be  x_oinc  for  the  output  array  and  16  *  x_xsize 
for  the  input  array,  the  x.size  must  be  16*x_xsize  for  both  arrays,  and  the  ysize 
must  be  x^ysize  for  both  arrays. 

SIDE  EFFECT:  Logically  OR’s  the  input  array  into  the  output  array.  Is  designed  as  a 
high  speed  function  used  a.s  a  primitive  function  in  the  bitgraph  package 
for  or*ing  characters,  pixel  shades,  contours,  etc  into  arrays. 

BUG:  The  current  code  will  not  work  on  a  right  to  left  computer  (in  the  tradition  of 
\'.AX  and  INTEL,  not  1B.\!  or  MOTOROLA)  unless  usliorts  do  not  have  to  be 
aligned  (which  iliey  do  not  on  u 

NOTE:  This  function  is  similar  to  Mxuor,  the  only  difference  being  that  ushorts  (16  bits) 
are  used  everywhere  in>ierid  of  ulonqs  (32  bits). 
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1.  GLOSSARY. 


*  Id-zerotransform* 

|LISP  Global  Variable] 

*ld-to2d-zero  transform* 

[LISP  Global  \'ariablej 

*  ld-to-3d-rero-transform  * 

[LISP  Global  Variable] 

*2d-to-ld-rero-transform* 

[LISP  Global  \'ariable] 

*  2d -zero- transform* 

[LISP  Global  ^'a^iable' 

*2d-to-3d-zero- transform* 

[LISP  Global  Variable. 

*3d-to-ld-zero-transform* 

[LISP  Global  Variable] 

*  3d- to-2d-zero- transform* 

[LISP  Global  \'ariable[ 

*3d-zero- transform* 

[LISP  Global  Variable! 

*  Id-unit-transform* 

[lisp  Global  Variable 

*2d-u  nit- transform* 

[LISP  Global  \’ariable[ 

*3d-u  nit-transform* 

[LISP  Global  Variable' 

sag_ld_zero_transform 

[0  Global  Variable] 

sag_ld_to_2d_zero_transform 

[C  Global  Variable] 

sag_ld_to_3d_zero_transform 

[C  Global  Variable] 

sag_2d_to_ld_zero_transform 

[C  Global  Variable] 

sag_2d_zero_transform 

[C  Global  Variable] 

8ag_2d_to_3d_zero_transform 

(C  Global  Variable] 

8ag_3d_to_ld_zero_transform 

(C  Global  Variable] 

8ag_3d_to_2d_zero_transform 

(C  Global  Variable] 

8ag_3d_zero_transform 

[C  Global  Variable] 

8ag_ld_unit_transform 

[C  Global  Variable] 

8  ag_2  d  _u  n  it_t  ran  s  f o  rm 

[C  Global  Variable] 

8ag_3d_unit_transform 

VALUE:  Unit  and  zero  transforms  of  the  given  dimensions. 

[C  Global  Variable] 

ANALYTIC  GEOMETRY 


10-1 


ANALYTIC  GEOMETRY 


10-2 


*3d-x-u  nit- vector* 
*3d-y-u  nit- vector* 
*3d-z-u  nit-vector* 
*2d-x-u  nit- vector* 
*2d-y- unit- vector* 
*ld-x- unit- vector* 
*3d-zero- vector* 

*2d- zero- vector* 

*  Id- zero- vector* 
*0d-vector* 

sag_3d_x_unit_vector 

sag_3d_y_unit_vector 

sag_3d_x_unit_vector 

sag_2d_x_unit_vector 

sag_2d_y_unit_vector 

sag_ld_x_unit_vector 

sag_3d_zero_vector 

sag_2d_zero_vector 

sag_ld_zero_vector 

sag_0d_vector 


[LISP  Global  Variable] 
■LISP  Global  Variable] 
;L1SP  Global  Variable] 
[LISP  Global  Variable] 
[LISP  Global  Variable] 
[LISP  Global  Variable] 
[LISP  Global  Variable) 
(LISP  Global  Variable) 
[LISP  Global  Variable] 
(LISP  Global  Variable] 


(C  Global  Variable] 
(C  Global  Variable] 
!C  Global  Variable] 
|C  Global  Variable] 
1C  Global  Variable] 
[C  Global  Variable] 
|C  Global  Variable] 
jC  Global  Variable: 
[C  Global  Variable] 
!C  Global  ^’^ariableJ 


\'.-\LUE:  Unit  and  zero  vectors  of  the  given  dimensions  and  in  theX.  Y,  and  Z  directions. 

(a-cluster  \has-poiiU-(irray  *ar_point-arrayj  [LISP  Macro] 

[lias-poivi-list  ’(pt_point-l  ...)] 

\i$-chaiu  ’g_chain-swiich] 

\i$-maximal-polygon  *g_inaximal-polygon-switch]) 


a-cluster 

cL 

(has-point-array  ’cLcIuster) 
(has-point-Iist  ’cLcluster) 
(is-chain  'cLcluster) 

(is-closed  ’cLcIuster) 
(Ls-maximal-polygon  ’cLcluster) 
(has-dimension  ’cLcluster) 
(has-count  ’cLcluster) 

“chain’’ 

“closed  chain” 

“edge  of  chain” 

“maximal  polygon” 

sag_cluster 

SAG^CLUSTER 

cLcluster— >sag_ctype 
cLcluster— >sag_cpar  ray 


[SKETCH  Type  Object] 
[Argument  Prefix] 

(SKETCH  Attribute  Macro] 
[SKETCH  Attribute  Macro] 
[SKETCH  Attribute  Macro] 
[SKETCH  Attribute  Macro] 
[SKETCH  Attribute  Macro] 
[SKETCH  Attribute  Macro] 
[SKETCH  Attribute  Macro] 

[SKETCH  Term] 
(SKETCH  Term] 
(SKETCH  Term] 
(SKETCH  Term] 

|C  Type] 
(C  Global  Variable] 
jC  Structure  Element] 
jC  Structure  Element] 
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cLcluster-->sag_cplist 
cLcI  list  er  —  >  sag_ccou  n  t 
cl_clusier— >  sagged  imension 
cLcluster~>sag_cchain 
cl.cliister— >sag_cclosed 
cLcliister— >sag_cmpolygon 

USE:  A’Ctusfer  is  a  sei  of  poinis.  All  the 
3. 


[C  Structure  Elenicni] 
[C  Structure  Elemenr 
[C  Structure  Elemenlj 
[C  Structure  Element] 
[C  Structure  Element] 
[C  Structure  Element] 

.5  must  have  the  same  dimension:  1,  2,  or 


The  set  of  points  can  be  specified  by  either  giving  the  has’poini-list  or  the 
potiit’orray  alI^ibule^.  The  former  is  a  list  of  Q’Vector^s  that  represent  points.  The 
later  is  an  army  wlio^c  X  dimension  size  equals  the  dimension  of  the  points  and 
whose  dimension  ecpials  the  number  of  points.  The  array  X  coordinate  values  0. 
T  and  2  correspond  lo  ihe  X.  ^  ,  and  Z  point  coordinates.  The  array  coordinate 
values  indcN  the  dillcreni  poinis 

•  Only  one  of  the  two  attributes.  hai>-poiui-li$(  or  has-poinUarray,  may  be  specified 
when  creating  n  cluster.  The  other  will  be  computed  if  accessed. 

A’Clnsfer  i>  n  chain  if  the  first  point  is  lo  be  thought  of  as  connected  to  the  second 
poini  the  second  point  is  connected  to  the  third  point,  etc.  Tlie  chain  is  closed  if 
the  Iasi  point  is  identical  to  the  first  point.  More  precisely,  O’Cluster  is-closed  if 
and  only  if  it  is  a  chain  wiih  ai  least  one  point  and  the  first  point  equals  (in  the 
sense  of  objeci-coiupare)  the  la^t  point  (all  chains  wdth  just  one  point  are  closed) 

The  edges  of  a  chain  are  the  line  segments  betw'een  consecutive  points. 

A  maximal  polygon  is  a  closed  chain  of  points  lying  in  a  plane  whose  edges  equal 
those  of  the  convex  hull  in  the  plane  of  the  chain’s  set  of  points.  The  ts-viaximal- 
polygon  attribute  is  t  if  the  chain  was  computed  in  a  way  that  makes  it  a  maximal 
polygon;  but  a  chain  may  still  accidentally  be  a  maximal  polygon,  even  if  the  value 
of  this  attribute  is  nit. 

HAS-POINT-ARRAY:  The  element  type  of  this  array  is  a-shorL  When  a-ctusUr  object  is 
created,  arrays  with  other  element  types  may  be  specified  as  the 
has’point’arrayj  but  they  will  be  copied  if  necessary  to  convert  the 
element  type  to  a-short. 

IS-MAXIMAL-POLYGON:  This  may  be  seif  (if  it  is  belately  realized  that  the  cluster  is  in 

fact  a  maximal  polygon). 

SAG.CPLIST: 

SAG.CPARRAY:  These  are  C  sai^lvaluc  values.  Sag^eparray  must  be  cast  to  a  C 

value  before  used. 

SAG.CCOUNT: 

SAG.CDIMENSION:  These  are  C  ini  values. 

SAG.CCHAIN: 
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SAC;.CCL<.)Sl-D. 

.^AG.CMPo!  YCOX  "J'hese  are  (tti-lbif  values  whic  h  take  the  C  values  0  and  1  for  the  LISP 
values  nil  and  I. 

SAG.CIA'STEH; 

SAG_CTVPE  A  LISP  u-ch^ier  object  is  a  C  sa<i^chister  structure.  Sag^ctypc  is  first  ele¬ 
ment  ol  an  sag^d aster  structure  in  C.  It  equals  SAG_CLUSTER.  which  in 
turn  equals— 

sob^nobject  ("a-cluster")’. 


(a-line  lias-start  *))t_siart 

hn.^’leiigth  ‘u_lenglli 
Jias-dtrecfioti  ’vec_(lirecl ion  ) 

(a-line  Ims-start  ’pi_start 

ha-^-end  ’))i_en(l  'g_infinile-.s\\  iich;) 

(a-line  has-sfarf  ’pi_si;iri 

has-segmeni  '\ec_seginenl  [is-infiiiite  *g_infinile-swit.ch]) 


[LISP  Macro; 


[LISP  Macro; 
[LISP  Macro; 


a-line 

[SKETCH  Type; 

lin_ 

[Argument  Prefix 

(has-length  din^IincA 

[SKETCH  Attribute  Macro] 

(has-start  *lin_liiu‘) 

[SKETCH  Attribute  Macro] 

(has-direction  lin_line) 

[SKETCH  Attribute  Macro] 

(has-end  dinjinc) 

[SKETCH  Attribute  Macro] 

(is-infinite  Minjine) 

[LISP  Macro] 

(has-segment  Min_line) 

[LISP  Macro] 

sag^line 

[C  Type] 

SAG^LINE 

(C  Global  Variable] 

lin  Jine— >sag_ltype 

[C  Structure  Element] 

linjine— >sag_llength 

[C  Structure  Element] 

lin_line—>sag_lin  finite 

[C  Structure  Element] 

linjine— >  sag^lstart 

[C  Structure  Element] 

lin  Jine— >8ag_lend 

jC  Structure  Element] 

lin  Jine— >8ag_ldirection 

USE:  A-tine  represents  a  finite  or  infinite  oriented  line. 

[C  Structure  Element] 

A  finite  line  has  a  has-start  point  and  a  has-end  point.  Its  has-length  is  the  distance 
from  the  start  point  to  the  end  point.  If  the  length  is  non-zero,  its  has-direction 
attribute  is  a  unit  vector  directed  from  the  start  to  the  end.  If  the  length  is  zero, 
the  has-direciioTi  is  nit. 

An  infinite  line  has  a  has-direcfioy}  attribute  which  is  a  unit  vector  in  the  direction 
of  the  line,  and  a  lias-siart  attribute  which  is  a  point  on  the  line,  and  which  must 
be  perpendicular  to  the  direction.  The  has-end  and  has-length  attribute  are  nil. 
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One  can  get  the  ba^^-.seejment  and  ib-iiijinlte  attributes  of  n  line,  but  these  are  not 
actually  stored  in  the  line.  The  hn.^-se(itnent  attribute  is  the  end  of  the  line  minus 
the  start  of  the  line  for  a  finite  line,  and  ml  for  an  infinite  line.  The  is-infinite 
attribute  is  /  for  an  inlinite  line  and  vil  for  a  finite  line 

Any  finite  line  may  also  be  made  by  giving  its  start  and  end,  or  by  giving  its  start 
and  a  has-i^egmeuf  value  from  which  the  end  can  be  computed.  An  infinite  line 
may  also  be  made  by  specif) mg  a  finite  line  as  just  mentioned  and  adding  a  /  is- 
ivfivitc  attribute 

Any  direction  given  when  (inline  is  created  does  not  have  to  be  a  unit  vector:  it  will 
be  converted  into  one.  It  will  also  be  converted  to  mV  if  the  length  is  given  as  zero. 
Similarly  the  start  given  for  an  inhniie  vector  does  not  have  to  be  perpendicular  to 
the  direction:  it  will  be  changed  lo  be  so 

SAG_LLENGTH: 

SAG^LINDNITE:  Sofullength  a  C'  Jiff  at  irhicb  takes  Ihe  value  SAT^FMISSING  if  the  line 
ii)fi)iite.  Sai]^htiji)iile  is  a  macro  that  tests  whether  sag^llength  is 
missing. 

SAG.LST.ART: 

SAG_LE.\D: 

SAG^LDIRECTION:  These  are  all  of  C'  iyi)e  sat^lvalue.  and  must  be  cast  to  the  C  type 
sag^vector  before  they  are  used. 

SAG.LINE: 

SAGJ-'HTE:  A  LISP  a-live  object  is  a  C  sag^line  structure.  Sag^llype  is  first  element  of 
a  sag^line  structure  in  C.  It  equals  SAG^LINE,  which  in  turn  equals— 

soh_uobject  ("a-line**). 

WARNING  ABOUT  COMPARE-OBJECT:  A-ltne  will  not  equal  itself  when  unevaPed  and  then 

re-eva/’ed.  Two  lines  computed  in  different  ways 
may  be  unequal  when  compared  with  compare- 
object,  even  though  they  are  supposed  to  be  equal 
in  theory. 

(an-ellipsoid  has- transform  ’trans_ortho  (LISP  Macro] 

has-xradii  *(n_xradius  [n_yradius  [n^zradius]]) 

\has-center  *vec_center]) 

(an-ellipsoid  has-radius  ’n_radius 

has-center  *Yec_center) 


an-ellipsoid 

elL 

(has-transform  ’elLellipsoid) 
(has-radii  ’elLellipsoid) 
(has-radius  ’elLellipsoid) 
(has-center  ’elLellipsoid) 


(SKETCH  Type] 
[Argument  Prefix] 

[SKETCH  Attribute  Macro] 
[SKETCH  Attribute  Macro] 
[SKETCH  Attribute  Macro] 
[SKETCH  Attribute  Macro] 
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(has-dimension  elLellipsoid)  [SKETCH  Attribute  Macro] 

RETURNS:  An-ellipf^e  objeci.  which  represents  a  finite  1,  2,  or  3  dimensional  ellipsoid. 

For  a  1  dimensional  ellipsoid,  n^yradius  and  n_2radius  are  nil.  Such  an  ellip¬ 
soid  is  just  a  pair  o)’  points.  For  a  2  dimensional  ellipsoid  only  n^zradius  is 
vil. 


Transform_ortho  is  an  orthogonal  point  transformation  which  defines  a 
transformed  coordinate  system.  In  the  transformed  coordinate  system  the 
ellipsoid  has  the  equation  — 


v^Tra 


■)*  +  (■ 


y 


v^yrodivs 


■)*  +  (■ 


n^zradius 


-f  =1.0 


(in  which  a  coordinate  is  omitted  if  its  corresponding  radius  is  nil). 


Transit ransforni  is  M  dimensional  if  the  space  in  which  the  ellipsoid  lives  is 
M  dimensional,  even  if  the  ellipsoid  has  fewer  dimensions. 


If  n_radius  and  vec_center  arc  given,  all  the  radii  are  equal,  the  dimension  M 
of  the  containing  space  is  the  dimension  of  vec_center,  the  linear  part  of  the 
transform  is  the  unit  transform  of  the  space,  and  vec_center  is  the  /m.v- 
displaceineot  part  of  the  transform. 

H.\S-RADIUS:  Equal  to  the  radii,  such  as  n_Nradius,  if  all  the  non-«:7  radii  are  equal  and 
the  dimension  of  the  space  containing  the  ellipsoid  equals  the  dimension  of 
the  ellipsoid.  Equal  to  nil  if  the  radii  are  unequal  or  the  dimension  of  the 
ellipsoid  is  less  than  the  dimension  of  the  space. 

HAS-CENTER:  The  center  of  the  ellipse:  —  ?  where  1  is  the  displacement  part  of 
trans_transform  and  T  is  the  linear  part. 

HAS-DIMENSION:  The  number  of  non-ruV  radii  from  among  n^xradius,  n_yradius,  and 
n^zradius. 

SAGJXLIPSOID: 

SAGJETYPE:  A  LISP  an~ellip$oid  object  is  a  C  sag^ellipsoid  structure.  Sag^eiype  is  first 
element  of  an  sag^ellipsoid  structure  in  C.  It  equals  SAG J)LLIPSOID, 
which  in  turn  equals— 

sob^nobject  (**an-ellipsoid**). 

WARNING:  An-ellipsoid  will  not  equal  itself  when  tinevafed  and  then  rc-euared.  Two 
ellipsoids  computed  in  different  ways  may  be  unequal  when  compared  with 
compare-objectj  even  though  they  are  provably  equal. 
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(angle-between-lines  lin_line-l  lin_line-2)  |LISP  Macro' 

RETURNS  The  floiuim  angle  in  radians  between  the  direction  vectors  of  the  lines.  The 
angle  is  in  the  range  ll  one  of  the  lines  is  a  zero  length  finite  line,  the 

result  is  vH. 

(angle- between-vectors  'vec_vector-l  ’vec_vector-2)  [LISP  Macro] 

WHERE:  Both  vectors  must  have  the  same  dimension. 

RETURNS.  The  flonuvi  equal  to  the  angle  between  the  vectors  in  radians.  Nil  if  one  of 
the  vectors  is  of  zero  length. 

In  order  to  get  accuracy,  two  different  methods  of  computation  are  used-  one 
for  the  case  where  the  vectors  are  nearly  parallel,  and  one  for  the  case  w  here 
the  vectors  are  nearly  perpendicular. 

(a-transform  7/u.s-j.r 'n_x\,  lias-iy  [SKETCH  Type  Macro 

!//ax<*-.rc  'n_.\Zj  [haS'Xt  ‘n^Ntj 
'lias-yr  'n_y\j  [liaa-yy  ’n_yyj 
.has-yz  ’n_yz  ha^s-yt  *n_yt' 
lhas-zx  *n_zx|  [ha^^-zy  ’n«zyj 
liaf>-zz  *n_zz  has^zt  ’n_zi 
JtaS'tx  'n_txj  \liQf>'iy  bi_tyj 
\has-tz  *n_tz|  [/ia5-//  ’n_ttj 
U^i-orthogonal  'g^orthogonalj 
[has-inpvi-diwensions  ^x_input-dimensions- 
[has- output- dimensions  ^x_output-dimensions]) 

(a-transform  [lias-displacement  Vec_displacement]  [SKETCH  Type  Macro] 

has- axis  ’vec_axis  has- angle  ’n_angle) 


a-transform 

trans_ 


[SKETCH  Type  Object] 
(Argument  Prefix] 


(has-inverse  ’trans_transform) 
(has-determinant  ^trans_transform) 
(has-axis  *trans_transform) 

(has-angle  ’trans^transform) 
(has-displacement  ’trans_transform) 
(is-Iinear  ’trans^transform) 

(is-affine  ’trans^transform) 

(Ls-orthogonal  ’trans_transform) 

(has- in  put-dimension  *trans_transform) 
(has-output-dimension  ’trans_transform) 


(SKETCH  Attribute  Macro] 
[SKETCH  Attribute  Macro] 
(SKETCH  Attribute  Macro] 
(SKETCH  Attribute  Macro] 
[SKETCH  Attribute  Macro] 
(SKETCH  Attribute  Macro] 
[SKETCH  Attribute  Macro] 
[SICETCH  Attribute  Macro] 
(SICETCH  Attribute  Macro] 
[SKETCH  Attribute  Macro) 


“linear  transform” 
“projective  transform” 
“orthogonal  transform” 
“affine  transform” 


(SKETCH  Term] 
[SKETCH  Term] 
[SKETCH  Term] 
(SKETCH  Term] 
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sag_transform 
SAG.TRANSFORM 
trans^traniform— >sag_ttype 
trans^transform— >sag_tlinear 
trans_transform— >sag_taffine 
trans_transform— >sag_torthogonal 
trans^transform— >sag_tidimension 
trans_transform— >sag_todirDension 
trans_transform — >  sag_txx 
trans_transform— >sag_txy 
trans_transform— >sag_txz 
trans^transform— >sag_txt 
trans.transform— >sag_tyx 
trans_transform— >8ag_tyy 
trans_transform— >sag_tyz 
trans^tran.sform— >sag_tyt 
trans_transform— >sag_tzx 
t  rans_transform  — >sag_tzy 
trans_Transform— >sag_tzz 
trans^lransform  — >sag_tzt 
transit  ransform  —  >sag_ttx 
t  ra  ns_t.ransform — >  sag_tty 
trans^transform— >sag_ttz 
trans^transform— >sag_ttt 


[C  Typel 
[C  Global  Variable] 
[C  Structure  Element] 
[C  Structure  Element] 
[C  Structure  Element] 
[C  Structure  Element] 
[C  Structure  Element] 
[C  Structure  Element] 
[C  Structure  Element] 
[C  Structure  Element] 
[C  Structure  Element] 
[C  Structure  Element] 
[C  Structure  Element] 
[C  Structure  Element] 
jC  Structure  Element] 
[C  Structure  Element 
[C  Structure  Element] 
[C  Structure  Element] 
[C  Structure  Element 
[C  Structure  Element] 
[C  Structure  Element’ 
[C  Structure  Element] 
[C  Structure  Element] 
[C  Structure  Element] 


WHERE:  Vec_axis,  if  given.,  must  be  a  unit  vector  with  has-lcngth  equal  to  1.0. 


USE:  A'iraiisform  object  which  is  a  linear,  affine,  or  projective  transformation  of  points. 
The  points  are  represented  by  a-vcc^or  objects. 


The  has-xx,  has-xy,  ...,  has-tt  attributes  are  called  the  coordinates  of  the  transfor¬ 
mation.  The  kj*th  coordinate  of  the  transform  multiplies  the  k*th  coordinate  of 
the  input  point  to  produce  a  term  in  the  j*th  coordinate  of  the  output  point.  The 
coordinates  are  converted  to  flonum's.  Missing  coordinates  are  set  to  nil. 

For  one  dimensional  transforms,  coordinates  involving  Y  or  Z  are  nil.  For  two 
dimensional  transforms,  coordinates  involving  Z  are  nil.  For  a  transform  from  3 
dimensional  space  to  2  dimensional  space,  the  XZ,  YZ,  and  ZZ  coordinates  are  nil, 
but  the  ZX  and  ZY  coordinates  are  not.  And  so  forth. 


The  T  dimension  is  used  for  projective  transforms.  Points  in  N  dimensions  are 
extended  to  N+1  dimensions  by  adding  a  T  coordinate  equal  to  1.  Then  the  N+1 
dimensional  point  is  transformed,  the  coordinates  of  the  result  are  divided  by  the  T 
coordinate  of  the  result,  and  the  T  coordinate  of  the  result  is  removed. 

A  linear  transformation  is  a  non-projective  transformation:  one  not  involving  the  T 
coordinate.  If  a  transformation  has  each  coordinate  involving  T  equal  to  nil  or  to 
either  0.0  for  non  TT  coordinates  or  to  1.0  for  the  TT  coordinate,  then  the 
transformation  is  deemed  to  be  linear  and  all  coordinates  involving  T  are  set  to  nil. 
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An  affine  transformation  is  a  projective  transformation  which  never  changes  the  T 
coordinate  of  a  point  (before  division)  Sucli  is  equivalent  to  a  linear  transforma¬ 
tion  followed  by  adding  a  vector,  called  the  displacement  vector  of  the  affine 
transformation  (vec_displacement ,  actually). 

If  a  non-linear  transform  has  its  XT,  and  ZT  coordinates  equal  to  ml  or  0.0, 
and  its  TT  coordinate  equal  to  vil  or  1.0,  the  transformation  is  deemed  to  be  affine, 
the  TT  coordinate  is  set  to  1.0.  and  any  of  the  XT,  YT,  and  ZT  coordinates  for 
which  X,  Y,  or  Z  is  an  input  dimension  are  set  to  0.0. 

A  transform  is  orthogonal  if  it  preserves  distances  and  orientations.  The  later 
means  that  no  reflections  are  involved  in  the  transformation.  An  orthogonal 
transform  may  be  linear  or  affine*  but  if  it  is  not  linear,  it  must  be  affine. 

G_orthogonal  is  non-n//  if  the  transform  was  computed  in  a  way  that  made  it 
orthogonal  If  g_orthogonal  is  hil.  the  transform  may  or  may  not  be  orthogonal  by 
accident. 

The  has-(lispl(icewenf  attribute  gives  an  alternate  representation  of  the  TX.  T'^  . 
and  TZ  coordinates  of  an  affine  transformation. 

The  ha^-axis  and  attributes  give  an  alternate  representation  of  the  XX, 

XY.  XZ.  X’X,  .  ^*Z.  ZX,  ZY,  and  ZZ  coordinates  of  an  orthogonal  3D  transform 
Vec^axis  must  be  a  unit  vector  with  lias-lerigtli  equal  1.0,  provided  n_angle  is  not 
0.0.  If  n_angle  is  0.0,  vec_axis  will  be  set  to  nil,  even  if  a  non-m7  value  is  provided. 
G_orthogonal  is  set  to  /  if  n^angle  is  not  nit. 

IS-UNEAR: 

IS- AFFINE: 

IS-ORTHOGONAL: 

SAG.TLINEAR: 

SAG^TAFFINE: 

SAG^TORTHOGONAL;  Attributes  W'hich  specify  the  kind  of  transformation.  See  USE 

above.  In  LISP  these  are  nil  or  t]  in  C  they  are  0  or  1. 

HAS-XX  .  .  : 

SAG.TXX  :  The  coordinates  of  the  transformation.  See  USE  above.  The  LISP  versions 
are  flonum's  (other  LISP  numbers  will  be  converted  to  flonum's  when 
stored).  The  C  versions  are  floats. 

HAS-INPUT-DIMENSIONS: 

HAS-OUTPUT-DIMENSIONS: 

SAG.TIDIMENSIONS: 

SAG.TODIMENSIONS:  The  dimension  of  the  points  input  to  or  output  from  the  transfor¬ 
mation.  0,  1,  2,  or  3.  The  LISP  versions  are  fixnum's;  the  C  ver¬ 
sions  are  inCs. 
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Normally  the  dimensions  are  computed  automatically.  However, 
the  input  dimension  cannot  be  computed  automatically  when  the 
output  dimension  is  0.  Also,  when  a  transform  is  created  from  a 
prototype  and  the  dimensions  are  changed,  the  new  dimensions 
have  to  be  given  explicitly. 

H.\S-IXV*ERSE:  (has-inverse  trans_transform)  is  a  a-fransjonn  that  is  the  inverse  of 
trans_transform.  This  attribute  of  trans_transform  is  computed  the  first 
time  it  is  needed.  For  non-affine  orthogonal  transforms  it  is  just  the  tran¬ 
spose. 

If  the  transform  is  not  invertible,  this  attribute  is  nil  when  computed. 
However,  the  fact  that  it  has  been  computed  and  found  to  be  nil  is 
remembered,  so  it  will  not  be  computed  again. 

If  the  transform  is  invertible, 

{ha^-inverse  { has- diverse  trans_transform)) 
is  identical  to  tran5_transform. 

The  inverse  of  an  affine  transform  is  affine.  The  inverse  of  an  orthogonal 
transform  is  orthogonal. 

The  inverse  of  a  projective  non-affine  transform  is  only  determined  up  to 
a  multiplier.  The  multiplier  is  set  so  the  TT  coordinate  of  the  inverse  is 
1.0,  if  this  is  reasonable  [check]. 

MAS-DETERMINANT:  {lias-delenninant  trans_transform)  is  a  flonum  which  is  the  deter¬ 
minant  of  the  part  of  trans_transform  that  does  not  involve  the  T 
coordinate.  It  is  undefined  (n//)  for  projective  non-affine  transfor¬ 
mations. 

It  is  computed  the  first  time  it  is  needed.  For  orthogonal 
transforms  it  is  equal  1.0. 

HAS-AXIS:  A-vec(or  which  is  the  axis  of  rotation  of  an  orthogonal  point  transformation. 

It  is  computed  the  first  time  it  is  needed.  It  is  nil  for  non-orthogonal 
transforms  and  for  the  unit  orthogonal  transform  (the  one  with  0.0  rotation 
angle). 

HAS-ANGLE:  A  flonuin  which  is  the  angle  of  rotation  in  radians  of  an  orthogonal  point 
transformation,  about  its  axis.  It  is  computed  the  first  time  it  is  needed.  It 
is  0.0  for  the  unit  transform,  and  nil  for  non-orthogonal  transforms. 

The  axis  and  angle  of  rotation  are  always  chosen  so  that  the  angle  of  rota- 

tion  is  always  >=  — ~  and  < 

2  2 

MAS-DISPLACEMENT:  The  displacement  part  of  an  affine  transformation.  Nil  for  non- 
affine  transformations. 

SAG.TRANSFORM: 
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SAG.TT'^TE:  A  LISP  a-transform  object  is  a  C  sag^transfonn  structure.  Sag^ttype  is 
first  element  of  a  sng^iransform  structure  in  C.  It  equals 
SAG_TRANSFORM,  which  in  turn  equals— 

sob^nohject  (*'a-transform*'). 


COMPUTING  TRANSFORMS  IN  C: 

SAG_VADJUST:  Transforms  which  are  empty,  that  is  have  all  attributes  missing,  can  be 
created  in  C  by  code  such  as— 

SQg^ialloc  (tr,  l) 

sob^vuiif  {{sat^lvalue)  tr,  SAG^TRANSFORM) 
or 

register  sag^traiisforjii  tr  =  {sob^lraiisform)  sob^vcreate  (SAG^TRANSFORM): 

Note  that  in  the  first  case  the  transform  is  in  the  stack,  and  cannot  not 
have  any  sag^taris.  sag^tdisplacemeiit,  or  sag^tiiiverse  elements  Serious 
problems  can  arise  if  one  attempts  to  compute  these  elements  for  a  stack 
transform. 

Note  that  in  the  second  case  the  transform  is  in  the  heap  and  must  be 
protected  from  garbage  collection  before  any  more  heap  allocations  are 
done. 

After  an  empty  transform  has  been  created,  it  may  be  completely  defined 
by  setting  its  non-missing  sag^txx,  $ag_txy,  ...  sag^ttt  coordinates,  its 
sag^tidhnension  and  sag^todwiension  dimension  sizes,  and  its 
sag^torthogonal^  sag^tlinear,  and  sag^taffine  flags.  The  dimensions  and 
flags  are  best  set  by  calling— 

s a g^tsdwi elisions  (tr) 
after  setting  the  coordinates. 

The  sag^orthogonal  flag  must  be  set  before  calling  sag^tsdimensions^  if  it 
applies  to  the  xx,  ...,  zz  coordinates.  Sag_isdimen$ions  will  clear  this  flag 
for  projective  transforms,  but  leaves  it  untouched  for  other  kinds  of 
transformations. 

The  tx,  ty,  and  tz  coordinates  can  be  set  by  calling— 

sag^tsdisplacement  (tr,  vec_displacement) 

and  the  xx,  xy,  xz,  yx,  yy,  yz,  zx,  zy,  zz  coordinates  can  be  set  by  cal- 
ling- 

sag^tsangle  (tr,  f_angle,  vec_axis). 

This  last  function  also  sets  sag^torthogonal.  Vec^axis  may  be  sat^nil  if 
f_angle  is  zero. 

There  are  a  variety  of  other  functions  for  setting  empty  transforms:  see 
sag^icompose,  sag^tsum^  sag^tdifference,  sag^tpscalar^  sag^tdiagonalj  etc. 


Printed  April  28,  1989 


ANALYTIC  GEOMETRY 


10-12 


W.\RN1NG  ABOrT  COMPARE  OBJECT:  Because  floating  point  numbers  are  not  exact,  out- 

putting  (i-transform  into  a  catalog  and  reading  it 
back  will  not  read  back  a-traixsform  that  is  exactly 
the  same  as  the  original.  Compare-object  will  gen¬ 
erally  consider  the  transforms  to  be  different. 


(a-vector  \lias-x  *n_x]  \has-y  ‘n^y  [Inis-z  ’n_z]] 

\has-length  ’n^length]) 

(has-x  ’vec_vector) 

(has-y  ’vec_vector) 

(has-2  Sec_vector) 

(has-length  'vec_vector) 

(has-dimension  ’vec_vector) 


[SKETCH  Type  Macro] 


[SKETCH  Attribute  Macro] 
(SKETCH  Attribute  Macro] 
(SICETCH  Attribute  Macro] 
[SKETCH  Attribute  Macro] 
[SKETCH  Attribute  Macro) 


a-vector 

vec_ 

pt_ 


(SKETCH  Type  Object] 
[Argument  Prefix] 
[Argument  Prefix] 


sag_vector 
SAG.VECTOR 
vec_vector— >sag_vtype 
vec_vector — >  sag_vx 
vec_vector— >sag_vy 
vec_vec  tor — >  s  ag_v  z 
sag_vlength  (vec_vector) 
sag_vadjust  (vec_vector,  fjength) 


[C  Type] 
[C  Global  Variable] 
[C  Structure  Element] 
[C  Structure  Element] 
[C  Structure  Element] 
[C  Structure  Element] 
[C  Macro] 
[C  Function] 


ARGUMENT  PREFIXES:  Vec_  and  p/_  both  denote  a-vector  objects.  The  former  is  used  to 

emphasize  that  the  object  represents  a  displacement  vector,  and 
the  later  to  emphasize  that  the  object  represents  a  point  in  space. 


USE:  A-vector  object  represents  a  relative  motion  in  space.  It  may  also  be  used  to 
represent  a  point  in  space  by  specifying  the  displacement  of  the  point  from  some 
origin. 


The  X,  Y,  and  Z  coordinates  are  stored  as  flonum^s.  Missing  y  and  z  coordinates 
are  set  to  nii  A  1-dimensional  point  or  vector  has  nil  y  and  z  coordinates,  while  a 
2-dimensional  point  or  vector  has  a  nil  z  coordinate. 


If  njength  is  given,  the  vector  coordinates  are  scaled  so  the  vector  is  of  the  given 
length.  A  unit  vector  can  be  made  by  specifying  njength  as  being  1.0. 

HAS-X,  ...: 

SAG_VX.  :  The  coordinates  of  the  point.  See  USE  above.  The  C  versions  are  float's. 
HAS-LENGTH: 

SAG^VLENGTH:  A  flonum  which  is  the  length  of  vec^vector.  It  is  an  attribute  of 
vec_vector  which  is  computed  the  first  time  it  is  needed.  For  unit  length 
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vectors  it  is  equal  1 .0. 

The  has-leugth  attribute  of  a-vector  is  not  printed  when  the  vector  is 
printed  unless  it  equals  1.0,  signifying  a  unit  vector.  Similarly  it  is  not 
returned  by  uneval-object  unless  it  is  1.0.  Lastly,  it  does  not  participate 
in  co7?ipare-o6jecf  comparisons  of  vectors. 


The  C  form,  sag^vlengih  (vec_vector),  is  a  macro  so  it  can  check  whether 
the  length  attribute  has  been  computed  yet,  and  call  a  function  to  com¬ 
pute  it  if  not.  This  macro  returns  a  float. 

SAG.VT'iTE:  A  LISP  a-vecior  object  is  a  G  sag^vector  structure.  Sag_viype  is  first  ele¬ 
ment  of  a  sag^vector  structure  in  C.  It  equals  SAG_VECTOR,  which  in 
turn  equals— 

sob^nobjecl  ("a-veclor"). 


COMPUTING  VECTORS  IN  C: 

$AC_V.aD.JUST:  Nectors  which  are  empty,  that  is  have  all  attributes  missing,  can  be 
created  in  C  by  code  such  as— 

sag^vallor  l) 


sob_vhut  {{sai^lvalue)  v,  SAG_\'ECTOR) 
or 

register  6a^;_vec/or  v  =  {sob_vector)  sob_vcreaie  {SAG_VECTOR); 

Note  that  in  the  second  case  the  vector  is  in  the  heap  and  must  be  pro¬ 
tected  from  garbage  collection  before  any  more  heap  allocations  are  done. 
Also  note  that  the  ‘v’  in  ‘sob_v’  refers  to  a~lisp~vector  and  not  a-vector. 


After  an  empty  vector  has  been  created,  it  may  be  completely  defined  by 
setting  its  non-missing  sag_vXj  sag_vy^  and  coordinates.  The  rule 

that  sag^vx  may  not  be  missing  if  $ag_vy  is  not  missing,  and  neither 
sag^vx  nor  sag^vy  may  be  missing  if  sag^vz  is  not  missing,  must  be 
obeyed.  No  other  attributes  of  the  vector  need  be  set. 


The  length  of  a  vector  may  be  set  or  changed  after  the  vector  coordinates 
have  been  set  by  calling— 

sag^vadjusi  (vec^vector,  fjength). 

The  sag_^)x^  sag^vy^  and  sag^vz  coordinates  of  the  vector  are  adjusted  by 
this  call  to  make  the  vector  length  equal  the  desired  length,  if  necessary. 

There  are  a  variety  of  other  functions  for  setting  empty  vectors:  see 
sag_tpoint^  sag^tvector,  sag^tcovector,  $ag_v$um,  $ag_vdxfference^ 
sag^vvxove^  sag^vpscalar^  sag^vpbetxveen^  sag^vunit^  etc. 

WARNING  ABOUT  COMP ARE^OBJECT:  Because  floating  point  numbers  are  not  exact,  out- 

putting  a-vecior  into  a  catalog  and  reading  it  back 
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will  not  read  back  a-vcctor  that  is  exactly  the  same 
as  the  original.  Coinpare-objcct  will  generally  con¬ 
sider  t  he  vectors  to  be  different. 

(center-of-gravity-of-cluster  cLcluster)  [LISP  Function] 

RETITRNS;  A  point  equal  to  the  center  of  gravity  of  the  points  in  the  cluster  (with  equal 
weighting  of  points).  Returns  inl  if  the  cluster  is  empty. 

(compose-transforms  ’trans_transform-l  ’trans_transform-2)  [LISP  Macro] 

RETURNS:  The  composition  of  the  two  transforms.  That  is,  the  transform  which  moves 
a  point  to  the  same  place  that  it  would  be  moved  by  first  applying 
trans_transform-l  and  then  trans_transform-2. 

(distance-between-lines  MinJine-1  ’linJine-2)  [LISP  Macro] 

RETURNS:  The  flonxnn  distance  from  linJine-1  to  the  lin_line-2.  If  both  lines  are 
infinite,  nearly  coplanar.  and  nearly  parallel,  the  distance  between  the  lines  is 
defined  to  be  the  distance  between  their  lias-start  points. 

(distance-between-point-and-line  ’pt_point  Min_line)  [LISP  Macro] 

RETITRNS:  The  floiium  distance  between  the  point  and  the  line. 

(distance-between-points  ’pt_pl  ’pt_p2)  [LISP  Macro] 

RETURNS:  The  flonum  distance  between  points  (represented  by  vectors).  Both  points 
must  have  the  same  dimension. 

(linearize-transform  ’trans_transform)  [LISP  Macro] 

RETURNS:  A  linear  transform  whose  X,  Y,  and  Z  coordinates  equal  those  of 
trans_transform. 

(lines-are-parallel  lin_line_l,  lin_line_2)  [LISP  Macro] 

RETURNS:  The  symbol  t  if  neither  line  is  zero  length  and  the  directions  of  the  lines  are 
parallel  according  to  vectors- arc-parallel.  Otherwise  returns  nil. 

(move-vector  ’vec^vector  ’n_x  [’n_y  [’n_z]])  [LISP  Macro] 

RETURNS:  A-vector  equal  to  vec^vector  with  n_x  added  to  its  x  coordinate,  n_y  to  its  y 
coordinate,  and  n_z  to  its  z  coordinate.  There  may  be  fewer  n_x,  n_y,  and 
n_z  arguments  than  the  dimension  of  vec_vector,  with  the  omitted  arguments 
being  treated  as  zero. 
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(point-between-points  ’pi.poini-1  ’pt_point-2  ’n^scalar)  (LISP  Macro] 

WHERE:  Both  points  must  have  the  same  dimension. 

RETURNS:  Point-befxreen-poinls  returns  a-vector  equal  to— 

n^scalar  *  pt_point-l  +  (1  -  n_scalar)  *  pt_point-2. 


(product-of-scalar-and-transform  *n_5calar  *trans_transform)  (LISP  Macro] 

RETURNS:  A-transJorrn  equal  to  the  scalar  product  of  n_5calar  and  trans_transform. 


(product-of-scalar-and-vector  ’n_scalar  Vec_vector)  [LISP  Macro] 

RETURNS:  /I -vec/or  equal  to  the  scalar  product  of  n_scalar  and  vec_vector. 


sag_langle  (lin_line_l  lin_line_2) 
sag_lpdistance  (vec_point  lin_line) 
sag_ldistance  (lin_line_l  linjine_2) 

RETURNS;  A  floating  point  number  equal  to— 


[C  F unction] 
[C  F unction] 
[C  Function] 


sag_langle  The  angle  in  radians  between  the  directions  of  the 

lin_line_l  and  Iin_line2.  Or  SAT_DMISSING  either  line 
is  of  zero  length. 


sag_lpdistance  The  distance  from  vec_point  to  linjine. 

sag_ldLstance  The  distance  between  the  lines.  If  the  lines  are  both  infinite 
and  are  parallel  according  to  sag_lparall€l,  then  this  is  the 
distance  between  their  has-start  points. 


sag_lparallel  (linjine_l,  lin_line_2)  (C  Function] 

RETURNS:  1  if  neither  line  is  zero  length  and  the  directions  of  the  lines  are  parallel 
according  to  sag_vparaUci  Otherwise  returns  0. 

sag_tpoint  (pt_result,  pt_point,  trans_transform)  [C  Function] 

8ag_tvector  (vec^result,  vec_vector,  trans^transform)  [C  Function] 

8ag_tcovcctor  (vec_result,  trans_transform,  vec_covector)  (C  Function] 

SIDE  EFFECT.  The  empty  vector  vec_result  (or  pt_result)  is  set  to  the  point,  vector,  or 
covector  transformed  by  trans^transform. 
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sag_tsproduct  (tians_tian?:;form_l  trans_transform_2)  [C  Function] 

RETl’RNS:  A  Ilonting  point  number  equnl  to  the  scalar  product  of  trans_transform«l  and 
trans_transform_2.  This  is  the  sum  of  the  products  of  corresponding  ele¬ 
ments.  as  in  the  scalar  product  of  two  vectors.  If  both  transforms  are  linear, 
the  tt  components  are  voi  included  in  the  sum. 


sag_tsum  (trans_transforin_l,  trans_transform_2.  trans_transform J3)  (C  Function] 

sag_tdifference  (trans_transform_l,  trans_transform_2,  trans_transform_3)[C  Function] 
sag_tpscalar  (trans_transform_l,  f^scalar,  trans_transform_2)  [C  Function] 

sag_tdiagonal  (trans_transforni_l,  x_dimension,  f^jscalar)  (C  Function] 

SIDE  EFFECT:  The  empty  transform  trans_transform_l  is  set  as  follows— 

sag^isuiv  The  sum  of  trans_transform_2  and  trans_transform_3. 

sag^tdifftrtnce  The  difference  trans_transform_2  minus  trans_transforni_3. 

sag^fpscalar  The  product  of  f_scalar  and  trans_transform_2. 


sag_f(lla(iot)al  The  x_dimensional  transform  with  the  value  f_scalar  for  all 
diagonal  elements  and  zeros  everywhere  else. 


The  output  transform  can  be  one  of  the  input  transforms  for  any  of  these 
functions.  If  there  is  an  error  in  any  of  these  functions,  the  output 
transform  may  be  set  to  an  inconsistent  state. 

sag_vdimension  (vec_vector)  [C  Function] 

RETURNS:  The  dimension  of  vec_vector  as  an  integer  (0,  1,  2,  or  3). 

sag_vparallel  (vec_vectorl,  vec_vector2)  [C  Function] 

RETURNS:  1  if  vec_vectorl  and  vec_vector2  both  have  non-zero  length  and  they  are 
parallel  in  the  sense  that  the  sin  of  the  angle  between  them  has  absolute  value 
less  than  0.001.  Otherwise  returns  0. 

The  number  0.001  is  choosen  because  if  the  sin  of  the  angle  between  the  vec¬ 
tors  is  X,  the  error  of  the  computed  unit  vector  that  is  perpendicular  to  the 
two  vectors  may  have  a  norm  as  large  as  10**-6/X.  The  10**-6  arrises 
because  the  coordinates  of  vectors  are  stored  in  single  precision  floating  pK)int. 

Thus  if  we  quantize  both  the  domain  of  angles  and  the  domain  of  unit  vec¬ 
tors,  we  get— 

(error  in  angle  domain)  *  (error  in  unit  vector  domain)  ==  10**“6. 

So  0.001  splits  the  difference  between  the  two  domains. 
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sag_vsproduct  (vec_vector_l  vec_vecl.or_’2)  [C  Function^ 

sag_vangle  (vec_vector_l  vec_vecior_2)  [C  Function’ 

sag_vdistance  (pt_point_l  pt_point._’2)  [C  Function] 

RETURNS;  A  floating  point  number  equal  to— 

sag^vsprodxicl  The  scalar  product  of  vec_vector_l  and  vec_vector_2. 

sag^vangle  The  angle  between  vec_vector_l  and  vec_vector_2,  in  radi¬ 
ans,  in  the  range  [0,  tt];  or  the  value  SAT^MISSING  if  one 
of  the  vectors  is  of  zero  length. 

In  order  to  get  accuracy,  two  difl'erent  methods  of  computa¬ 
tion  are  used:  one  for  the  case  where  the  vectors  are  nearly 
parallel,  and  one  for  the  case  where  the  vectors  are  nearly 
perpendicular. 


$ag_vdi$tunce 


The  distance  between  pt_point_l  and  pt_point_2  (length  of 
their  difference). 


sag_vsum  (vec_vector_l,  vec_vecior_’2,  vec_vector_3) 
sag_vdifTerence  (vec_vector_l,  vec_vector_2,  vec_vector_3) 
sag_vpscalar  (vec_vector_l ,  f_scalar.  vec_vector_2) 
sag_vvproduct  (vec_vector_l,  vec_vector_2.  vec_vector_3) 
sag_vpbetween  (pt_point_l,  pt_point_2,  pt_point_3,  f^calar) 
sag_vunit  (vec_vector,  x_unit_dimension,  x_totaLdimension) 


[C  Function^ 
[C  Function 
[C  Function 
[C  Function 
[C  F unction] 
[C  F unction] 


SIDE  EFFECT:  The  empty  vector  vec_vector_l  (or  pt_point_l)  is  set  as  follows— 


sag^vsum 


The  sum  of  vec_vector_2  and  vec_vector_3. 


sag^vdxfftrtnct  The  difference  vec_vector_2  minus  vec_vector_3. 


$ag_vpscalar 

sag^vvproduct 

sag^vpbelween 

sag^vunit 


The  product  of  f^calar  and  vec_vector_2. 

The  vector  product  of  vec_vector_2  and  vec_vector_3. 

The  sum  of  f_scalar  times  pt_point_2  and  (1.0  —  f_scalar) 
times  pt_point_3. 

The  unit  vector  with  dimension  x^totaLdimension  in  the  in 
the  x_unit_dimension  direction  (0  for  X,  1  for  Y,  2  for  Z). 


The  output  vector  (or  point)  can  be  one  of  the  input  vectors  for  any  of 
these  functions  (even  $ag_vvector).  If  there  is  an  error  in  any  of  these 
functions,  the  output  vector  may  be  set  to  an  inconsistent  state. 
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(scalar-product-of-transforms  ’trans_transform-l  ’trans_transform-2)  [LISP  Macro] 
WHERE:  Both  transforms  must  have  the  sanae  dimensions. 

RETURNS:  A  flommi  equal  to  the  scalar  product  of  trans_transform-l  and 
trans_transform-2.  The  scalar  product  is  the  sum  of  the  products  of  com¬ 
ponents.  as  for  a  vector.  If  both  transforms  are  linear,  the  tt  components  are 
not  included  in  the  sum. 


(scalar-product-of-vectors  Sec_vector-l  ’vec_vector-2)  [LISP  Macro] 

WHERE:  Both  vectors  must  have  the  same  dimension. 

RETURNS:  A  flonuin  equal  to  the  scalar  product  of  vec_vector-l  and  vec_vector-2. 

(sum-of-transforms  ’trans_tl  ’trans_t2)  [LISP  Macro] 

(difference-of-transforms  'trans_tl  ■trans_t2)  [LISP  Macro] 

WHERE:  Both  transforms  must  have  the  same  dimensions. 

RETURNS:  A-transform  equal  to  the  sum  of  trans_tl  and  trans_t2,  or  the  sum  of 
trans_tl  and  minus  trans_t2. 


(sum-of-vectors  'vec_vl  'vec_v2)  [LISP  Macro] 

(difference-of-vectors  ’vec_vl  ’vec_v2)  [LISP  Macro] 

WHERE:  Both  vectors  must  have  the  same  dimension. 

RETURNS:  A-vector  equal  to  the  sum  of  vec_vl  and  vec_v2,  or  the  sum  of  vec_vl  and 
minus  vec_v2. 


(transform-line  ’lin_line  ’trans_transform)  [LISP  Function] 

RETURNS:  A-lme  equal  to  linjine  transformed  into  the  coordinate  system  obtained  by 
transforming  points  by  trans_transform  (see  trayisform-point). 


This  is  just  a  matter  of  transforming  the  start,  end,  and  direction  of  linjine 
by  trans_transform. 


(transform-point  ’pt_point  ’trans_transform) 

(transform-vector  ’vec_vector  ’trans_transform) 
(transform-covector  ’trans_transform  ’vec_vector) 

RETURNS:  A-vector  equal  to  the  pt^point  or  vec_vector 
trans_transform. 


[LISP  Macro] 
[LISP  Macro) 
[LISP  Macro) 

transformed  by 


Transform-vector  ignores  the  T  coordinate,  using  only  the  XX,  XY,  YZ,  YX, 
YY,  YZ,  ZX,  ZY,  and  ZZ  coordinates  of  transjransform.  This  has  the  effect 
of  transforming  a  displacement  vector,  rather  than  a  point.  It  will  not  work 
if  trans_transform  is  projective  but  not  affine. 

Transform-covector  is  like  transform-vector  but  transforms  the  vector  by  the 
transpose  of  the  transformation.  In  general— 
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(scalar-product-of-vectors  (translorm-vector  v  T)  w ) 

(scalar-product-of-vectors  v  (transform-covector  T  \v)). 

NOTE:  The  argument  order  is  determined  by  thinking  of  vectors  as  row  vectors,  and 
covectors  as  column  vectors.  The  ik’th  element  of  a  transform  corresponds  to 
row  i  and  column  k. 

(transpose-transform  ’trans_transform)  [LISP  Macro) 

RETURNS:  The  transpose  of  the  linear  transform  trans^transform. 

(vector-product-of-vectors  *vec_vector-l  Vec_vector-2)  [LISP  Macro] 

v^TiERE:  The  vector  arguments  must  be  3D. 

RETURNS:  A~vcctor  equal  to  the  vector  product  of  vec_vector-l  and  vec_vectoi-2. 

(vectors-are-parallel  Aec_vector-l  ’vec_vector-2)  [LISP  Macro] 

WHERE:  Both  vectors  must  have  the  same  dimension. 

RETURNS:  The  symbol  i  if  vec_vectorl  and  vec_vector2  both  have  non-zero  length  and 
they  are  parallel  in  the  sense  that  the  sin  of  the  angle  between  them  has  abso¬ 
lute  value  less  than  0.001.  Otherwise  returns  0. 

The  number  0.001  is  chosen  because  if  the  sin  of  the  angle  between  the  vec¬ 
tors  is  X,  the  error  of  the  computed  unit  vector  that  is  perpendicular  to  the 
two  vectors  may  have  a  norm  as  large  as  l0**-6/X.  The  10**-6  arises 
because  the  coordinates  of  vectors  are  stored  in  single  precision  floating  point. 

Thus  if  we  quantize  both  the  domain  of  angles  and  the  domain  of  unit  vec¬ 
tors,  we  get— 

(error  in  angle  domain)  *  (error  in  unit  vector  domain)  ==  10**-6. 

So  0.001  splits  the  difference  between  the  two  domains. 

(zero-transform  *x_dimension)  [LISP  Macro] 

(unit-transform  ’x_dimension)  [LISP  Macro] 

RETURNS:  A  zero  or  unit  transform  whose  dimension  is  x_dimension. 
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(zero-vector  ’x_total-dimension)  [LISP  Macro] 

(unit-vector  \'_unit-dimension  ■x_total-dimension)  [LISP  Macro] 

RETURNS:  A  vector  whose  dimension  is  x_total-dimension.  The  vector  components  are 
all  zero  for  zero-vector,  and  are  all  zero  except  for  the  x_unit-dimension’th 
component,  which  is  1.0,  for  unit-vector,  where  x_unit-dimensioD  is  0,  1,  or  2 
to  denote  the  X-dimeusion,  Y-dinie7ision,  or  Z- dimension. 


Printed  April  28,  1989 


CHAPTER  11 


4 


DISPLAY 


1.  USING  DISPLAYS.  A  display  is  an  array  of  pixels.  For  example,  the  SUN  low 
resolution  frame  buffer  is  an  array  of  640X475  pixels:  640  pixels  wide  and  475  pixels  high. 

A  display  has  an  intensity  array  with  stores  for  each  pixel  a  code  for  a  color  and  an 
intensity.  Usually  this  is  an  8-bit  code  with  256  possible  values.  One  value  encodes  black. 
127  values  encode  127  intensity  levels  of  white,  from  dark  gray  to  bright  white.  16  levels 
encode  16  intensity  levels  magneta  (purple),  from  dark  magenta  to  bright  magneta. 
There  are  also  16  intensity  levels  for  each  of  7  other  colors:  red,  brown,  yellow,  cyan, 
green,  tur(|uoise,  and  blue. 

Just  to  start  out.  the  commands— 


— >  [clear- display) 

—  >  [flush- display) 

will  clear  the  display.  Most  display  functions  just  act  on  an  in-computer-memory  copy  of 
the  display.  Flush-display  is  required  to  move  this  out  to  the  display  proper. 


You  can  write  an  image  into  the  current  display  with  the  display-image  function 
For  example— 

— >  [display-image  [an-array  has-sizes  ’{64  64) 

by-expression  ’(-f  X  (*  64  Y)))) 

— >  [flush-display) 


will  display  the  array  as  a  black-and-white  image.  As  an  alternative— 

— >  [display-image  (an-orray  has-sizes  ’(8  16) 

by-expression  ’(-f  X  (*  8  Y))) 

’(100  200)  has-zooms  ’(20  10) 
has-bounds  ’(-0.5  pseudocolor  127.5)) 

— >  [flush- display) 

will  display  an  image  so  that  its  upper  left  point  has  coordinates  (100  200)  (100  pixels  hor¬ 
izontally  from  the  left  and  200  vertical  down  from  the  top),  will  make  each  pixel  20  times 
as  larger  horizontally  and  10  times  as  large  vertically  (the  has-zooms)^  and  will  display 
the  image  using  a  pseudocolor  scale  instead  of  a  gray  scale.  In  the  pseudocolor  scale  there 
are  only  16  intensities,  but  each  is  modulated  by  8  colors,  in  order  to  permit  small 
differences  of  intensity  to  show  up.  According  to  the  has-bounds  argument,  the  array  ele¬ 
ment  value  range  from  -0.5  through  127.5  is  divided  into  128  equal  intervals  each  mapped 
onto  a  different  intensity  code  by  the  pseudocolor  scale.  See  display-image  in  the  GLOS¬ 
SARY  for  details. 


Instead  of  flushing  the  display  to  the  display  device,  you  can  write  the  display  into  a 
catalog,  read  it  back,  and  display  it  by  commands  such  as— 
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—  >  (iiclq  c  (a-cafolog  lia:^-file  loo)) 

—  (u'rile-ilisplay  c) 

(close-display  c) 

— >  (playback- ilii>pl(iy  [read- catalog  c)) 

See  write-display  nnci  playback-display  in  the  GLOSSARY  for  more  details. 

A  display  can  also  have  bitgraph  planes.  Each  bitgraph  plane  has  one  bit  per  pixel. 
The  bitgraph  planes  are  eacli  associated  with  an  intensity  array  code  value  that  specifies  a 
color  and  an  intensity.  When  a  bitgraph  plane  pixel  bit  has  the  value  ‘T,  the  plane’s  code 
value  replaces,  or  overlays,  the  code  value  speciHed  for  the  pixel  by  the  display’s  intensity 
array.  But  if  the  bit  ha5  the  value  ‘O',  there  is  no  overlay,  and  the  intensity  array’s  code 
value  is  used. 

If  there  are  several  bitgraph  planes,  they  have  a  priority  ordering,  with  the  higher 
priority  planes  overlaying  the  lower  priority  ones.  It  is  standard  for  a  display  to  have  the 
following  nine  bitgraph  planes— 

blue  turquoise  cyan  yrten  yellow  brown  red  magenta  white. 

Each  of  iht'se  bitgraph  plane>  is  displayed  a.s  the  brightest  intensity  of  the  color  which 
names  the  plane.  The  priority  of  these  planes  is  from  lowest  to  highest  in  the  above  list: 
u7n7e  overlays  everything,  while  blue  is  overlaid  by  all  other  planes. 

Text  can  be  displayed  by  commands  such  as  the  following— 

—  >  {dear-display) 

—  >  (display-patorn  ’[Hello  There|  (20  300)  Wight-rotate  Wurquoise) 

— >  (display-text  (20  ’(300  50)  2  0  'left  Wyaii) 

(patoin  ’[This  is  a  list-|) 

(terpri) 

(pretty-print  ’((Feb  1  1987)  (file  l)  (image  1)))) 

— >  (flush-display) 

Display-patom  displays  the  text  ‘Hello  There’  centered  on  the  coordinates  (20  300).  This 
text  is  rotated  90  degrees  to  the  right,  and  displayed  in  the  turquoise  plane.  Display-text 
above  displays  the  text  written  by  the  patom,  terpri,  and  pretty-print  statements  within 
the  body  of  display-text.  The  pretty-print  assumes  a  line  length  of  20.  The  text  is  located 
in  the  cyan  plane  at  the  coordinates  (300  50):  it  is  vertically  centered  on  these  coordi¬ 
nates,  but  horizontally  it  is  left  adjusted  so  these  coordinates  appear  just  to  the  left  of  the 
text.  The  character  size  is  2.0  times  the  normal  size.  See  display-text  in  the  GLOSSARY 
for  more  details. 

Lines  can  be  displayed  by  commands  such  as— 
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->  idisplay^lifie.^  ^yellow  ^(300  0)  (500  0)  ’(500  100)  ’(300  150)  ’(300  0)) 

—  >  (sety  m  {quotient  pi  180.0)) 

“>  (5c/^  circle  {av-array  lutfi-sizei>  ’(2  361) 

by-expressiott  \if{eqiutl  X  0) 

(5ni  (product  m  Y)) 

(co5  (product  m  Y))))) 

— >  (display- lines  (netv-triiidotr  ’(95  295)  lias-zootns  ’(50  50) 

has-sizes  ’(2.2  2.2)  has-cursor  ’(0.6  0.6)) 

'‘green  3.0  circle) 

—  >  (flush-display) 

The  first  display^nes  command  draws  4  straight  lines  between  the  successive  points, 
forming  a  box  in  the  yellow  pinne.  The  second  display-lives  command  draws  straight  lines 
between  successive  points  defined  by  a  2X361  array.  The  array  has  been  defined  so  that 
these  points  will  outline  a  unit  circle.  To  position  and  size  this  circle,  a  window  on  the 
display  has  been  created  by  the  netp-triudow  function.  The  window  has  apparent  size 
2. 2X2. 2,  but  the  zooms  are  both  50,  so  the  windou  is  110X110  display  pixels  in  size.  The 
window  has  a  cursor  which  is  placed  at  the  center  of  the  window,  because  the  circle  will 
be  centered  on  the  ctirsor  (the  circle  coordinates  range  from  -1  through  -hi).  The  reason 
the  center  of  the  window  is  at  coordinates  (0.6  0.6)  instead  of  (1.1  1.1),  is  that  the  origin 
(0  0)  is  in  the  center  of  the  upper  left  pixel  of  the  window,  so  that  the  upper  left  corner  of 
the  window’  has  coordinates  (-0.5  -0.5).  The  window  must  be  made  a  little  larger  than  the 
circle  to  ensure  that  no  lines  of  the  circle  are  partly  omitted,  as  they  would  be  if  any  part 
of  them  extended  beyond  the  w'indow. 

The  second  display-lines  command  draws  lines  that  are  three  display  pixels  wide,  as 
indicated  by  the  3.0.  The  first  display-lines  command  draws  lines  that  are  the  default  of 
1.0  display  pixels  wide.  The  widths  of  lines  and  sizes  of  text  do  not  depend  on  the  zooms, 
unlike  the  sizes  of  pixels  drawn  with  display-image. 

The  circle  can  be  by  using  a-transforjn  instead  of  a  window.  The  commands— 

— >  (display- lines  (a-transform  has-xx  30  ha$-xy  0 

lias-yx  0  lias-yy  30 

has-displacemeni  (a-vector  has-x  150  has-y  350)) 
'brown  2.0  circle) 

— >  (flxtsh- display) 

draw  a  concentric  circle  3/5’ths  as  large  as  the  previous  circle  (radius  30  instead  of  50) 
with  a  line  width  of  2.0  pixels  instead  of  3.0  pixels  and  the  color  brown  instead  of  green. 

See  display-lines  in  the  GLOSSARY  for  more  details. 

2.  WINDOWS. 

3.  MAKING  DISPLAYS. 
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4.  GLOSSARY. 

(a-display  [haa-sizes  (x^xsize  x^ysize)]  [SKETCH  Type  Macro) 

|/ir/5-n2flp  *s_map-nnme] 

[has-device  ’(s_clcv ice- type  ...)j 
[lias'fibn 

\ha$-pareut  ■'d\vin_windo\v] 

[has-biigroph-planes  '(s_plane-type-nanie-l  ...)] 

[has-mteiisity-array  ’ucar/usar/s_intensity- array] 

[has-bilgraph-array  ’ubar/s_bitgraph-arrayj 
[has-bif graph- programs  ’h/s_bitgraph-programs]) 


dis_  [Argument  Prefix] 

a-display  [SKETCH  Type  Object] 


“Bitgraph  Plane  Name'' 
bpn_ 


[SKETCH  Term] 
[Argument  Prefix] 


(has-sizes  ’dis.display) 

(has-map  ’dis_display) 

(has-device  ’dis_display) 

(has-iilm  ’dis_display) 

(has-parent  'dis_display) 

(has-in tensity- array  ’dis_display) 
(has-bitgraph-planes  ’dis_display) 
(has-bitgraph-array  'dis.display) 
(bas-bitgraph-programs  ’dis_display) 
(has-range  ’dis_display) 
(has-primary-colors  ’dis_display) 
(has-colors  ’dis_display) 

(has-8cales  ’dis^display) 
(has-plane-types  ’dis_display) 


[SKETCH  Attribute  Macro] 
[SKETCH  Attribute  Macro] 
[SKETCH  Attribute  Macro] 
[SKETCH  Attribute  Macro] 
[SKETCH  Attribute  Macro] 
[SKETCH  Attribute  Macro] 
[SKETCH  Attribute  Macro] 
[SKETCH  Attribute  Macro] 
[SKETCH  Attribute  Macro] 
[SKETCH  Attribute  Macro] 
[SKETCH  Attribute  Macro] 
[SKETCH  Attribute  Macro] 
[SKETCH  Attribute  Macro] 
[SKETCH  Attribute  Macro] 


USE:  A-display  is  a  representation  of  a  black-and-white  or  color  image.  The  representa¬ 
tion  has  three  parts.  First,  there  is  an  intensity  array,  which  stores  a  gray  or  color 
scale  intensity  image.  Second,  there  is  an  ordered  set  of  bitgraph  programs,  each 
of  which  is  a  list  of  vectors,  text,  and  fill  areas  that  can  be  used  to  draw  a  binary 
image  which  is  called  a  bitgraph  plane.  Third,  there  is  a  bitgraph  array,  which 
directly  stores  all  the  bitgraph  planes  as  binary  images. 


Any  of  the  three  parts  may  be  omitted. 


A-display  may  be  just  a  means  of  storing  information,  or  it  may  be  an  actual  out¬ 
put  device  display.  The  latter  has  a  non-nil  has-device  attribute  that  specifies  the 
nature  of  the  output  device.  An  output  display  can  also  store  information  in  any 
way  a  non-output  display  can,  except  that  an  output  display  cannot  store  informa¬ 
tion  its  hardware  cannot  output. 

Writing  information  into  a  display  stores  the  information  inside  the  computer. 
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For  an  output  display,  the  copy  of  this  information  stored  in  the  computer  is  usu¬ 
ally  not  tlie  same  as  the  copy  stored  in  the  output  device.  To  move  the  latest  copy 
from  the  computer  to  the  output  device,  an  additional  operation,  flush- display, 
must  be  performed  on  the  output  display.  This  operation  ensures  that  the  output 
device  holds  the  same  information  as  the  computer. 

A-dtsplay  may  be  copied  into  part  of  a  larger  display  by  the  in trgt- display  func¬ 
tion.  If  the  display  has  a  non-TiiV  has-parcni  attribute,  then  an  operation  such  as 
flush-display  that  outputs  the  display  will  merge  it  into  the  parent  and  flush  the 
parent. 

The  X  dimension  of  a  display  is  horizontal  with  X  increasing  from  left  to  right. 
The  Y  dimension  is  vertical  with  Y  increasing  from  top  to  bottom.  The  coordi¬ 
nates  of  display  pixels  and  the  sizes  of  display  dimensions  are  integers  (unlike 
display  windows  where  they  are  floating  point). 

A  display  ha.s  X  and  Y  dimension  sizes  given  by  x_xsize  and  x_ysize.  Both  inten¬ 
sity  and  bitgraph  arrays  have  these  same  X  and  Y  dimension  sizes,  and  the  infor¬ 
mation  stored  in  array  elements  with  particular  X  and  Y  coordinates  determines 
what  is  displayed  in  the  pixel  at  corresponding  horizontal  and  vertical  coordinates 
on  a  display  screen. 

The  has-map  attribute  of  a  display  is  used  to  look  up  a-display-viap  (any  one  of 
several  with  the  same  primary  name  will  do),  and  the  has-range,  has-primary- 
cotors,  has-colors,  has-scales,  and  has- plant- types  attributes  of  the  display  are 
inherited  from  this  display  map.  See  a- display -map  for  the  meanings  of  these  attri¬ 
butes. 

If  the  has-devtce  attribute  is  given,  it  implies  that  only  certain  has-sizes  and  has- 
map  values  are  legal.  In  fact,  neither  of  these  attributes  need  be  given  in  this  case, 
for  both  will  receive  default  values  implied  by  the  has-device  value.  Similarly  the 
has-parent  attribute  can  imply  these  and  other  display  attribute  values. 

If  the  has-primary- colors  attribute  is  not  nil,  its  length  is  the  Z  dimension  size  of 
the  intensity  array,  and  its  ciments  are  the  colors  cooresponding  to  the  different  Z 
coordinates  (0,  1,  2,  ...  in  that  order).  But  if  the  has-primary- colors  attribute  is  mV, 
the  intensity  array  has  Z  dimension  size  1,  and  the  array  stores  codes  that  are 
mapped  by  some  display  map  onto  different  colors.  In  this  case  the  map  from 
codes  to  colors  is  determined  from  the  software  view  by  has-map,  and  from  the 
hardware  view  by  has-map,  has-device,  and,  when  a  camera  is  being  used,  by  has- 
film. 

The  has-bitgraph-planes  attribute  specifies  a  bitgraph  plane  type  name  for  each  bit- 
graph  plane.  These  type  names  are  looked  up  in  the  has- plane- types  attribute  to 
give  a-plane-type  object  for  each  bitgraph  plane.  This  specifics  the  color,  line  type 
(solid,  long-dashed,  etc.),  character  font  (display,  times-roman,  times-bold,  etc.), 
area  fill  pattern,  normal  line  width,  and  normal  character  size  for  the  plane. 
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The  bitgraph  array  stores  one  plane  for  each  of  its  Z  coordinates.  Bitgraph  planes 
are  named  by  the  Z  coordinates  they  would  have  were  there  a  bitgraph  array.  The 
elements  of  the  has-bitgraph-plaues  list  are  for  the  planes  with  Z  coordinates  0,  1, 
2,  in  that  order.  The  number  of  elements  in  this  list  equals  the  Z  dimension  size 
of  the  bitgraph  array. 

Bitgraph  planes  with  higher  Z  coordinates  overlay  those  with  lower  Z  coordinates. 

BITGRAPH  PLANE  NAMES: 

BPN.:  The  name  of  a  bitgraph  plane  in  a-display  can  be  its  Z  coordinate,  which  is  an 
integer.  Or  the  name  can  be  a  pair,  (type-name  M),  if  the  plane  is  the  M'th  plane 
in  the  has-biigraph-plants  list  that  has  the  given  type  name.  Lastly,  the  name  can 
be  a  type  name  by  itself,  to  name  the  first  plane  with  the  given  type  name  in  the 
has-bilgraph-plancs  list  (i.e.  M  =  1  implied). 

MERGING  DISPLAYS:  A  display  used  to  store  information  is  often  merged  into  a  display- 
used  to  output  information.  This  is  easy  and  obvious  when  both 
displays  have  the  same  resolution,  Aas-map,  and  and  lias-bitgraph- 
planes  attributes,  but  can  become  difficult  or  impossible  in  other 
cases. 


Intensity  arrays  can  be  scaled  to  output  devices  of  different  resolu¬ 
tion,  but  usually  the  results  will  look  nice  only  when  the  scale  fac¬ 
tors  are  integers  or  the  resolution  of  the  output  display  is  very 
much  higher  than  that  of  the  input  display. 

Bitgraph  arrays  simply  cannot  be  scaled  to  different  resolutions. 

Bitgraph  programs  are  easily  scaled  to  any  resolution.  If  bitgraph 
planes  are  to  be  scaled  later,  they  should  be  stored  in  bitgraph  pro¬ 
gram  form,  even  if  they  are  also  stored  (redundantly)  in  bitgraph 
array  form. 

The  has-scales  attribute  of  a  display  is  used  when  images  is  stored 
in  the  intensity  array,  and  cannot  meaningfully  be  changed  when 
the  intensity  array  is  merged  later  into  another  display. 

Similarly  most  of  the  has-plane-types  attribute  information  is  used 
when  images  is  stored  in  a  bitgraph  array,  and  cannot  meaningfully 
be  changed  when  the  bitgraph  array  is  merged  later  into  another 
display.  The  one  exception  is  the  plane  color,  which  can  be  changed 
(see  a- plane- type). 

In  fact,  the  colors  of  planes  can  be  changed  when  they  are  merged 
later  into  another  display,  as  long  as  the  planes  are  stored  in  bit- 
graph  array  or  bitgraph  program  form. 

Any  attribute  inherited  from  the  ha$-map  display  map  can  be 
changed  when  a  bitgraph  program  is  merged  later  into  another 
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display.  This  includes  all  the  lias-plane-iypes  information  Thus 
bitgraph  programs  are  very  flexible. 

A’ display  objects  can  be  stored  on  disk  and  played  back:  i.e.,  read 
and  merged  into  an  output  display.  In  general,  storing  information 
solely  in  an  intensity  array  is  very  device  dependent,  but  provides 
the  fastest  playback.  Storing  as  much  information  as  possible  in 
bitgraph  programs  maximizes  device  independence,  but  slows  play¬ 
back.  Bitgraph  arrays  are  an  intermediate  step  between  bitgraph 
programs  and  intensity  arrays,  and  their  use  provides  some  flexibil¬ 
ity  (colors  can  be  changed  and  planes  selected  or  omitted,  but  reso¬ 
lution  cannot  be  changed)  with  some  playback  speed  loss. 

HAS-SIZES:  The  horizontal,  or  X  coordinate,  size  in  pixels,  and  the  vertical,  or  Y  coordi¬ 
nate.  size  in  pixels. 

The  hos-sizes  attribute  can  be  implied  by  the  has-dcvicc  or  has-parevt  attri¬ 
bute.  or  can  be  directly  specified,  but  must  not  end  up  being  nil. 

RA$-M\P;  This  attribute  provides  the  primary  part  of  the  name  of  O’display-inap.  which 
in  turn  provides  the  hos-range,  has-primary-colors,  has-colors,  has’scales,  and 
has-plane-fypes  at  tributes. 

The  has-ivap  attribute  can  be  implied  by  the  has-device  or  has-porcni  attri¬ 
bute,  or  can  be  directly  specified,  but  must  not  end  up  being  rnl. 

The  most  common  values  for  this  attribute  are  standard  for  displays  with 
intensity  arrays,  and  standard-bitgraph  for  arrays  with  no  intensity  arrays. 

Displays  with  the  standard  has-map  value  store  an  8-bit  code  for  each  pixel  in 
an  intensity  array  that  has  a  Z  dimension  size  of  1  and  a  has-range  attribute 
equal  to  256.  The  8-bit  codes  are  mapped  to  particular  colors  and  intensities 
by  display  maps  with  this  primary  name.  The  has-primary- colors  attribute  in 
this  case  is  nil. 

Displays  with  the  standard-bitgraph  has-map  value  have  no  intensity  array, 
but  only  bitgraph  planes. 

The  has-map  attribute  value,  s_map-name,  is  merely  part  of  the  name  of  the 
display  map  that  will  actually  be  used.  It  is,  however,  the  part  of  the  name 
important  to  the  programmer.  The  other  parts  of  the  map  name  arc  used  to 
select  slightly  different  maps  depending  on  the  monitor,  camera  film,  frame 
buffer,  and  display  processor  being  used,  but  all  the  slightly  different  maps 
with  the  same  s_map-name  are  intended  to  give  essentually  the  same  visual 
result. 

See  a^ display-map. 

HAS- RANGE: 
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RAS- PH  I NL-Vin  -  COLORS : 

RAS-COLORS. 

RAS-SC.-VLES: 

R\S-PLANE- TATES:  These  attributes  are  inherited  from  a-dtsplay-rnap  named  by  the 
has-nxip  attribute.  See  HAS-MAP  above  and  a- display ’map. 

RAS-BITGRAPH-PL.ANES:  This  attribute  is  a  list  whose  elements  are  the  type  names  of  the 

display's  bitgraph  planes.  The  type  names  are  looked  up  in  the 
bas’ plane- types  attribute  to  find  a-plane-type  objects  that 
specify  the  color,  line  type,  character  font,  area  fill  pattern,  nor¬ 
mal  character  size,  and  normal  line  width  associated  with  each 
plane. 

The  elements  of  the  has-bitgraph-planes  list  correspond  to  the 
planes  with  Z  coordinates  0,  1,2,  ...,  in  that,  order.  The  length 
of  the  list  determines  the  number  of  planes.  There  may  be  at 
most  32. 

The  has-bifyraph-planes  attribute  defaults  to  the  bitgraph 
planes  of  the  bos-pareuf  attribute  if  this  latter  attribute  is  non- 
nil. 

RAS-INTENSITA '•.VRR.VA':  The  intensity  array  is  an  array  of  a-ucbar's  if  the  lias-range 

attribute  is  not  greater  than  256,  or  an  array  of  a-usliorfs  oth¬ 
erwise.  Its  X  and  Y  dimension  sizes  are  x_xsize  and  x^ysize.  Its 
Z  dimension  size  is  1  if  the  has-primary-colors  attribute  is  ni7, 
and  is  otherwise  the  length  of  the  has-primary-colors  list. 

This  attribute  may  be  given  the  explicit  values  nil  ot  <  when  the 
display  is  created,  to  indicate  whether  the  intensity  array  is  to 
be  absent  or  present.  If  no  explicit  value  is  given,  an  intensity 
array  is  created  for  the  display  if  the  has-ranges  attribute  is  not 
nf/,  unless  the  display  has  a  has-pareni  with  no  intensity  array 
or  a  has-device  that  does  not  support  intensity  arrays. 

RAS-BITGRAPRARRAY:  The  bitgraph  array  is  an  array  of  a-ubiVs.  Its  X  and  Y  dimen¬ 
sions  are  x^size  and  x_ysize.  Its  Z  dimension  is  the  number  of 
bitgraph  planes,  which  equals  the  length  of  the  has-bitgraph- 
planes  list. 

This  attribute  may  be  given  the  explicit  values  nil  or  t  when  the 
display  is  created,  to  indicate  whether  the  bitgraph  array  is  to  be 
absent  or  present.  If  no  explicit  value  is  given,  a  bitgraph  array 
is  created  for  the  display  if  the  has-bitgraph-planes^  has-colors, 
and  has-plane-types  attributes  are  not  nt7,  unless  the  display  has 
a  has-parent  with  no  bitgraph  array  or  a  has-device  that  docs  not 
support  bitgraph  arrays. 

HAS-BITGRAPRPROGRAMS:  This  is  a  hunk  whose  length  is  the  number  of  bitgraph  planes 

and  whose  elements  are  the  bitgraph  programs  for  the 
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planes,  in  Z  coordinate  order. 

This  ai  tribute  may  be  given  the  explicit  values  nil  or  t  when 
ilie  display  is  created,  to  indicate  whether  the  bitgraph  pro¬ 
grams  are  to  be  absent  or  present.  If  no  explicit  value  is 
given,  a  bitgraph  programs  are  created  for  the  display  if  the 
hdi^-bilgraph-plaves  attribute  is  not  ni7,  unless  the  display  has 
a  has-pareuf  with  no  bitgraph  programs  or  a  has-devicc  that 
(Iocs  not  support  bitgraph  programs. 

HAS-P.ABENT:  If  non-;/// this  is  a  window  into  which  the  display  is  merged  by— 

(displaij-merge  dis_display  dwin_parent) 

(Jl usli  -  display  cl  w  i  n_par  cn  t) 

every  time  the  display  is  flushed.  Expose- display  similarly  merges  the 
display  into  its  parent  and  calls  expose- display  on  the  parent.  Lastly 
close-display  2iho  calls  itself  on  the  parent. 

A  display  also  gets  default  values  for  its  has-sizes^  has-map^  and  has- 
bif graph-planes  attributes  from  its  has-parenf.  The  in  addition  the  display 
will  not  ac(|Uirc  ha.s-ndensiiy-array.  has- bitgraph- array,  or  has-btigraph- 
proyranis  by  default  if  its  has-parent  does  not  have  them. 

H.AS-DEMCE:  This  is  n  list  that  (Ic.-^ic ribes  the  hardware  that  implements  the  display,  if 
there  is  such  (many  displays  are  merely  used  for  storage)  The  following 
are  the  possible  values— 

(network  <hosi>  <port>  <device>  <processor>  <monitor>  <camera>) 

A  display  accessible  through  the  network  via  the  display 
deamon  system.  The  <host>,  <port>,  and  <dcvice> 
are  as  described  in  the  appendix  on  DISPLAY  DEAMONS. 
The  <host>  and  <port>  identify  the  server;  the  <dev- 
ice>  identifies  a  particular  display  device  on  the  <host> 
(the  server  services  many  displays  on  the  same  host). 

The  <processor>,  <monitor>,  and  <camera>  are  as 
described  under  a-display-map  SJPROCESSOR, 
SJvIONITOR,  and  S_CAMERA.  They  arc  used  to  help 
select  the  display  dcvicc*s  pseudocolor  map  and  camera 
parameters  (Aos-map-array  and  has-camera-parameters  at¬ 
tributes  of  a- display-map). 

_ <camera>  may  be  omitted  if  there  is  none. _ 


HAS-FILM:  This  is  as  described  under  a- display- map,  SJ'ILM.  It  is  used  to  select  the 
pseudocolor  map  and  camera  parameters  (Aos-map-array  and  has-camera- 
parameters  attributes  of  a- display-map)  during  an  expose- display  operation. 
This  has-film  attribute  may  be  set/  at  any  time  in  order  to  allow  changing 
films. 
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(a-display-map  lia.s-uLs  [SKETCH  Type  Macro] 

*((s_map-nanie  [s.monitor  [s^film]  (s.processorjj)  ...) 
\hos-prtwanj‘Colors  *(s_prim ary-color- 1  ...)] 

\has~rott(ie  ’x_rangej 
\h(is-n)op-array  ’ucar_map-arrayj 
[lidii’Camera-paraincfcrs  ’g_cainera-paraineters] 
j/?as-co/or5 ’((s_color-l  (\_color-ll  ...)  ••)] 

\ha.s-iicales  ’((s_scale-l  iicar/usar_scale-l)  ...))] 

\lias-plane‘ types  *((s_plane-type-l  plt_plane-type-l)  ...))]) 


dmap_ 

a-display-map 

(has-ids  ‘(lmap_map) 
(has-primary-colors  'dniap_mnp) 
(has-range  *clinap_ninp) 

(has-map-array  '(hnap_map) 

(has-colors  ’(lniap_niap) 

(has-scales  '(lnia])_map) 

(has-plane-types  ’(lninp_map) 

USE:  A- display- map  provides  various  maps 


(Argument  Prefix] 
[SKETCH  Type  Object] 

[SKETCH  Attribute  Macro] 
[SKETCH  Attribute  Macro] 
[SICETCH  Attribute  Macro] 
[SKETCH  Attribute  Macro] 
[SKETCH  Attribute  Macro] 
[SKETCH  Attribute  Macro] 
[SKETCH  Attribute  Macro] 

at  relate  to  particular  display  hardware. 


The  has-inap-arroy  attribute  is  used  with  color  displays  whose  intensity  array 
records  only  one  integer  per  pixel.  It  maps  these  integers  onto  color  intensity  N- 
tuples  used  by  a  color  display  monitor. 


The  has- cav) era-parameters  attribute  is  used  with  displays  that  have  camera 
hardware.  Camera  parameter  settings  determine  how  colors  will  look. 


The  has-colors  attribute  is  an  association  list  that  maps  color  names  onto  intensity 
array  values.  For  example,  a  color  named  red  would  map  onto  the  intensity  array 
value  that  gives  the  brightest  red  color. 


The  has-scales  attribute  is  an  association  list  that  maps  names  of  scales  onto 
scales.  A  scale  maps  a  set  of  equal  sized  intervals  onto  intensity  array  values.  For 
example,  a  scale  named  red  might  map  16  intervals  onto  16  different  intensity  lev¬ 
els  of  the  color  red. 


The  has-plane-types  attribute  is  an  association  list  that  maps  names  of  bitgraph 
plane  types  into  a-plane-type  objects  that  parameterize  bitgraph  planes.  E.g.  The 
name  red-italic  might  map  onto  a-plane-type  object  with  has-color  red  and  has-font 
display- italic. 

The  has-range  and  has-primary-colors  attributes  of  a  display  map  parameterize  the 
intensity  array  of  any  display  using  the  map.  The  has-range  attribute  specifies  the 
range  of  values  that  the  elements  of  the  array  may  take.  The  has-primary-colors 
attributes  specifies  the  Z  dimension  size  of  the  array,  and  the  color  associated  with 
each  Z  coordinate.  It  is  nil  when  the  Z  dimension  size  is  1  and  the  Z  coordinate  is 
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not  associalecl  with  colors,  as  is  the  case  when  the  map  has  a  non- nil  has-map-orray 
at  tribute. 

Display  maps  have  ID  s  that  name  them.  The  ID  s  principal  part  is  ’s_map-name. 
ID  s  have  secondary  parts.  s_monitor,  s_film,  and  s_processor,  which  name  the 
monitor,  the  film  for  camera  monitors,  and  the  display  processor  used  by  the 
display  hardware.  Different  display  maps  with  the  same  s_map-name  can  be  used 
to  provide  different  lios-niop-array's  and  ha^i-camcra-paraiuders  for  different  moni¬ 
tors,  films,  and  processors.  The  idea  is  that  all  display  maps  with  the  same 
s_map-name  should  look  the  same  to  the  person  viewing  the  display,  and  the 
differences  in  monitors,  films,  and  processors  should  be  compensated  for  by  chang¬ 
ing  has-inap-array  ^nd  ho^-comtr(i-p(irQmeieri>. 

When  a  display  map  is  made  it  is  filed  in  a  data  base  from  whence  it  can  be 
retrived  via  the  fiud-display-iuap  function.  It  is  filed  in  this  data  base  under  each 
of  its  different  ID  s,  and  for  each  ID  replaces  any  previous  display  map  of  that  ID  in 
the  data  ba.se  The  function  rentake-display-maps  is  useful  for  revising  this  data 
base. 

Display  map  attributes  are  used  only  in  certain  conte.vts.  and  need  not  be  present 
or  correct  in  conte.xts  where  they  are  not  used.  Uas-range,  liai:-prtinary-colors, 
has-colors,  and  lias-scales  are  used  only  for  displays  which  have  intensity  arrays. 
Has-plane-iypes  is  used  only  for  displays  which  have  bitgraph  programs.  Has- 
map-array  is  used  only  with  displays  that  have  display  hardware;  and  has-caniera- 
paramefers  only  with  displays  that  have  camera  hardware. 

• 

All  display  maps  with  the  same  s_map-name  should  have  the  same  has-range^  has- 
primary- colors,  ha$-colors,  has-scales,  and  has-plane-iypes  attributes  if  the  maps 
are  for  displays  with  intensity  and  bitgraph  arrays. 

HAS-RANGE:  The  elements  of  the  display’s  intensity  array  must  be  in  the  range  from  0 
through  x.range— 1. 

X^range  must  not  be  greater  than  65536.  If  x_range  is  not  greater  than 
256,  the  intensity  array  elements  must  be  of  type  a-uchar.  Otherwise  they 
must  be  of  type  a-ushort. 

The  has-range  attribute  is  nil  if  display’s  with  this  map  have  no  intensity 
array. 

HAS- PRIMARY-COLORS:  The  primary  colors, 

(s_prim  ary-color- 1  ...) 

name  the  Z  subscripts  of  a  display’s  intensity  array.  A  typical 
value  is— 

(red  green  blue) 
when  the  Z  dimension  size  is  3. 

If  has-priivary-colors  is  nil,  the  intensity  array  (if  it  exists)  has 


Printed  April  28,  1989 


DISPLAY 


11-12 


only  one  integer  element  per  pi,\el,  its  Z  dimension  size  equals  1. 
and  the  has-  map-array  attribute  maps  the  intensity  integers  onto 
color  intensities  (see  below).  The  has-primary-colors  attribute 
must  be  nil  if  the  has-viap-array  ztlnhute  is  non-nil. 

R-\S-M\P- ARRAY:  For  a  display  associated  with  a  non-njY  has-map-array,  ucar_map- 
array,  each  pixel  in  the  intensity  array  is  represented  by  a  single 
integer  that  may  be  used  as  a  Y  coordinate  to  access  a  row  of 
ucar_map-array.  The  elements  of  this  row  represent  the  intensities  of 
colors  in  a  manner  understood  by  the  hardware  named  by  the  has-tds 
attribute.  Ucar_map-array  has  x_range  rows. 

Typically  x_range  is  256  and  ucar_map- array  has  3  columns  with 
intensities  for  the  colors  red,  green,  and  blue,  in  that  order. 

Ucar_array  may  be  nil  when  a-display-map  is  being  used  for  the  sake 
of  its  has-colors.  has-scales.  has-planc-types,  and  has-range  attributes, 
rather  than  for  its  ability  to  specify  a  map  array  for  particular  display 
hardware.  It  must  be  nil  when  the  has-primary-colors  attribute  is 
non- nil.  or  when  the  has-range  attribute  is  nil. 

H.AS-CAMERA*P.\RAMETERS:  The  has-cantera-paramelers  attribute  is  a  lisp  object  that 

sets  the  camera  parameters  for  the  camera  named  by 
s_camera  (see  HAS-IDS).  Its  form  depends  upon  the  type  of 
camera  For  the  Matrix  camera,  it  is  a  symbol  which  when 
view'ed  as  a  character  string  equals  the  response  given  by 
the  camera  to  the  pair  of  commands— 

M 

P 

A  typical  value  is  for  a  color  picture  is— 

Mcsa#i 

P#1  COLOR  EX800  R{R500G750B650) 

C(R095G084B108)  B(R378G378B378) 

I 

while  a  typical  value  for  a  black  and  white  picture  is— 
IMWNA#1 

P#1  NEC  EX120  C077  B310 

I 

HAS-IDS:  The  map  may  be  denoted  by  one  of  many  ID’s.  These  give  a  generic  map 
name,  s_map“name,  the  name  of  a  monitor,  s.monitor,  and  the  name  of  a 
frame  buffer  processor,  s^processor.  An  example  ID  is— 

[standard  mit$ubishi-c-S910  sun-47^- 

Here  standard  names  the  map  from  the  programmers  point  of  view, 
mitsubislii-c-S910  names  the  monitor  (T.V.  display),  and  sun-475  names  the 
display  processor  which  stores  the  image  in  a  digital  frame  buffer  and  converts 
it  to  analogue  monitor  signals. 
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Anotlier  example  ID  is— 

(stnvdard  watrix  polaroid-559  svv-^^S). 

This  ID  is  used  with  camera  hardware.  The  camera  monitor  is  a  ynatrir  which 
includes  one  of  several  camera  mounts^  and  the  film  type  is  polaroid-559.  The 
has-v}(ip-(irray  and  haS’Carvera-paramelers  attributes  need  to  be  matched  to 
the  camera  monitor  and  film  type  for  best  results. 

An  ID  may  be  made  less  specific  by  omitting  components  at  its  end.  Display 
maps  are  stored  in  a  data  base  when  they  are  made,  and  may  be  retrieved  by 
the  find-display-map  function  using  the  ID’s  to  identify  the  map. 

All  display  maps  with  the  same  s_map>-name  are  intended  to  give  the  same 
visual  result.  The  s_monitor,  s_film,  and  s_processor  components  of  the  name 
are  intended  to  make  minor  modifications  to  the  map  in  order  to  give  the  same 
visual  result  on  different  monitors  and  with  different  processors.  All  maps  with 
the  same  s_map-name  should  have  equal  has-raiige,  has-prirnary-colors. 
colorfi.  hns-scalcs,  and  has-planc’typcs  attribute  values  if  the  maps  are  for 
displays  that  have  intensity  or  bitgraph  arrays.  However,  the  display  package 
makei>  no  check  of  this  rule. 

S_M\P-NM1E:  The  most  common  value  for  s_map-name  is  standard.  This  map  ha.s  an 
x_range  of  256  and  is  as  follows— 


Intensity  Array 

Hardware 

Element  Value 

Color 

Intensities 

0 

black 

0 

1-127 

white 

32,  34,  35,  ... 

,  255 

128-143 

magenta 

85,  96,  108,  . 

..,  255 

144-159 

red 

85,  96,  108,  . 

..,  255 

160-175 

brown 

64,  77,  89,  .. 

.,  255 

176-191 

yellow 

64,  77,  89,  ... 

,  255 

192-207 

green 

64,  77,  89,  .. 

.,  255 

208-223 

cyan 

64,  77,  89,  .. 

,,  255 

224-239 

turquoise 

64,  77,  89,  .. 

„  255 

240-255 

blue 

85,  96,  108,  . 

..,  255 

If  the  actual  hardware  intensities  for  each  color  are  on  a  scale  from  0 
through  255,  they  will  be  chosen  so  that  the  most  intense  color  component 
will  have  an  actual  hardw^are  intensity  equal  to  the  hardware  intensity 
given  in  the  above  table. 

S310NIT0R:  The  following  are  some  possible  s^monitor  values— 
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mitsubishi-c-3910 

Mitsubishi  C-3910  monitor. 

mitsubishi-c-3419 

Mitsubishi  C-3-119  monitor. 

mitsubishi-c-3919 

Mitsubishi  C-3919  monitor. 

S_C\MERA: 


The  following  are  some  possible  s_camera  values— 


matrix 


Matrix  Camera. 


S.FILM:  The  following  are  some  possible  s_film  values— 


polaroid-559 

Polaroid  559  film. 

polaroid-809 

Polaroid  809  film. 

polaroid-891 

Polaroid  891  film. 

polaroid-552 

Polaroid  552  film. 

kodak-\TS-III 

Kodak  VPS  Ill  film. 

S«PROCESSOP%:  Some  possible  values  for  s_processor  are— 


comtal-512 

COMT.'VL  \’ision-One '20  display  processor 
organized  as  a  5l2X512x8-bit  frame  buffer. 

sun-475 

SUN  C-lOX-lToXS-bit  frame  bufl’er. 

H.'VS-COLORS:  This  attribute  is  a  list  of  the  form  — 

((s_color-l  (x_color-ll  x_color-12  ...))  (s_color-2  (x_color-22  ...))  ...) 

which  maps  symbols  naming  colors  to  lists  of  integers  that  that  represent 
intensity  array  elements.  The  integers  in  one  list  represent  the  different  Z 
components  of  one  intensity  array  pixel  value.  The  number  of  integers  in 
the  list  must  equal  the  Z  dimension  size  of  the  intensity  array.  If  this  size 
is  1,  the  list  of  one  integer  may  be  replaced  by  a  single  integer,  as  in  — 

((s_color-l  x_color-l)  (s_color-2  x_color-2) ...). 

By  way  of  example,  any  standard  display  map  (see  S3iAP-NAME  above) 
has  the  following  value  for  its  has-colors  attribute— 

((black  0)  (white  127)  (magenta  143)  (red  159)  (brown  175)  (yellow  191) 
(green  207)  (cyan  223)  (turquoise  239)  (blue  255)) 

HAS-SCALES:  A  scale  maps  N  equal  sized  intervals  of  the  real  line  onto  N  different  inten¬ 
sity  array  pixel  values.  The  scale  does  not  itself  specify  the  locations  of  the 
intervals:  it  is  merely  a  vector  of  N  pixel  values.  This  vector  is  actually  an 
array  (e.g.  ucar/usar_scale-l)  whose  Y  dimension  indexes  the  intervals. 
Thus  the  Y  dimension  size  is  the  number  of  intervals.  The  X  dimension  of 
this  scale  array  corresponds  to  the  Z  dimension  of  the  display’s  intensity 
array:  each  scale  array  row  gives  the  Z  components  for  one  intensity  pixel. 

The  lias-scales  attribute  maps  scale  names  such  as  s_scale-l  onto  scale 
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arrays  such  as  ucar/usar_5cale-l. 


If  s_map-name  is  standard,  the  following  scale  names  are  defined  by  has- 
scales— 


Scale 

Name 

Number  of 
Intervals 

Value 

black 

1 

Pure  black. 

gray 

127 

Dark  gray  to  bright  white. 

pseduocolor 

128 

16  intensity  levels,  near  black  to  white, 
modulated  by  8  colors  in  the  order  magenta, 
red,  brown,  yellow,  green,  cyan,  turquoise, 
blue. 

positive 

64 

16  intensity  levels,  near  black  to  white, 
modulated  by  4  colors  in  the  order  green, 
cyan,  turquoise,  blue. 

negative 

64 

16  intensity  levels,  white  to  near  black, 
modulated  by  4  colors  in  the  order  magenta, 
red.  brown,  yellow. 

colors 

9 

9  colors  on  the  order  magenta,  red,  brown, 
yellow,  green,  cyan,  turquoise,  blue,  white. 
Each  color  is  represented  by  its  brightest  in¬ 
tensity  level. 

magenta 

16 

16  intensity  levels,  from  dark  magenta  to 
bright  magenta. 

red 

16 

16  intensity  levels,  from  dark  red  to  bright 
red. 

brown 

16 

16  intensity  levels,  from  dark  brown  to 
bright  brown. 

yellow 

16 

16  intensity  levels,  from  dark  yellow  to 
bright  yellow. 

green 

16 

16  intensity  levels,  from  dark  green  to  bright 
green. 

cyan 

16 

16  intensity  levels,  from  dark  cyan  to  bright 
cyan. 

turquoise 

16 

16  intensity  levels,  from  dark  turquoise  to 
bright  turquoise. 

blue 

16 

16  intensity  levels,  from  dark  blue  to  bright 
blue. 

HAS-PLANE- TYPES:  A-plane-type  specifies  parameters  used  in  drawing  a  bitgraph  plane: 

color,  line  width  in  pixels,  line  type  {solid,  long-dashed,  dot-dashed), 
character  size,  character  font  [display,  times-roman,  times-italic, 
times-bold),  character  size  in  pixels,  and  fill  pattern  [nil  is  the  default 
which  means  solid  fill).  The  has-plane- types  attribute  maps  plane 
type  names  such  as  s_plane-type-l  onto  plane  types  such  as 
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plt_plane-type-l. 

The  sliindard-bllgraph  display  map  defines  the  plane  names  white, 
magenta,  red,  brown,  yellow,  green,  cyan,  turquoise,  and  blue.  If 
color  is  available  these  all  have  the  display  font,  a  line  width  of  1.0, 
and  the  line  type  solid.  If  color  is  not  available  these  plane  type 
names  are  defined  as  follows— 


Plane  Type 

Line 

Line 

Name 

Font 

Width 

Type 

white 

romon 

1.0 

solid 

red 

ro7nan 

1.0 

lonq-dashcd 

green 

roman 

1.0 

doited 

turquoise 

ro7nan 

10 

doi-dashcd 

yellow 

roman 

1.0 

sliort’dashed 

magenta 

bold 

2.0 

long-dashed 

cyan 

bold 

2.0 

doited 

blue 

bold 

2.0 

dot -dashed 

brown 

bold 

2,0 

short- dashed 

Slatidard  display  maps  provide  the  same  plane  type  names  as 
standard-bitgraph  maps.  Standard  display  maps  work  only  with 
displays  that  acutally  have  color  available.  In  all  cases  the  line  type 
is  solid. 

The  normal  character  size  for  both  standard  and  standard-bitgraph 
plane  type  names  is  (6  12):  that  is,  6  pixels  wide  and  12  tall.  The 
display  font  provides  different  fonts  for  the  character  sizes  (relative 
to  6X12)  1.0,  1.2,  1.5,  2.0.  2.7,  3.2,  and  4.2.  The  width  of  the  charac¬ 
ters  is  the  controlling  dimension,  so  for  example  the  1.5  character  set 
is  1.5*6  =  9  pixels  wide. 

(a-display-wincfow  has-parent  ’dis/dwin_parent  [SKETCH  Type  Macro] 

|/ios-sjzcs  ’(n_xsize  n_ysize)| 

\has-upper-left  ’dwpt_upper-left] 

\has-lower-right  ’dwpt_lower-right] 

[/los-orjpjns  ’dwpt_origins] 

\has-200Tns  ’(n_xzoom  n_yz<x)m)] 

\has- orientation  ’s_orientation] 

[has- transform  ’trans_transform] 

[/los-cursor  ’dwpt_cursor] 

[has-plane  ’bpnjine-plane] 

[has-line-plane  ’bpnjine-plane] 

[/las-orcfl-p/onc  ’bpn_area-plane] 

[has-text-plane  ’bpnjext-plane]) 
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dwin_ 

a-display- window 


[Argument  Prefix] 
[SKETCH  Type  Object] 


■'display  window  point  ' 
dwpt_ 

(has-parent  '(I\vin_display) 
(has-sizes  ’d\vin_display) 

(h as-upper-left  ’dw  in_display) 
(has- lower-right  ’dwin_display) 
(has-origins  *dwin_display) 
(has-zooms  ’d\vin_display) 
(has-orientation  ’dwin_display) 
(has-transform  *dwin_display) 
(has-cursor  ’d\vin_display) 
(has-plane  ’d\vin_display) 
(has-line-plane  d\vin_display) 
(has-area-plane  'dwin^display) 
(has- text- plane  '(I\vin_display) 


[SKETCH  Term] 
[Argument  Prefix] 

[SKETCH  Attribute  Macro] 
[SKETCH  Attribute  Macro] 
(SICETCH  Attribute  Macro] 
[SKETCH  Attribute  Macro] 
(SI^TCH  Attribute  Macro) 
(SKETCH  Attribute  Macro] 
[SI^TCH  Attribute  Macro] 
[SKETCH  Attribute  Macro] 
[SKETCH  Attribute  Macro) 
[SKETCH  Attribute  Macro] 
[SKETCH  Attribute  Macro] 
[SKETCH  Attribute  Macro] 
[SKETCH  Attribute  Macro] 


*  current-display- window* 
(get-current-display- window) 
*playback-display-window'* 
(get-play  back-display- window) 


[LISP  Global  \'ariablej 
[LISP  Macro] 
[LISP  Global  Variable) 
[LISP  Macro] 


USE:  A-display-windoir  specifies  the  context  parameters  used  by  display  commands. 
Included  are  parameters  for  translating  the  command  coordinates  into  display 
coordinates,  for  clipping  lines,  images,  and  text  that  fall  outside  a  rectangular 
display  region,  for  determining  the  current  cursor  position,  and  for  selecting  the 
current  bit  plane  with  which  characters  and  lines  are  drawn. 


•CURRENT-DISPLAY- WINDOW: 

GET-CURRENT-DISPLAY-WINDOW:  The  *  current- display- window*  variable  holds  a- 

display- window  value  which  is  the  display  window 
upon  which  most  display  commands  operate  by 
default. 


This  variable  can  also  hold  a  function  or  lambda 
expression  to  be  funcalFed  to  return  a-display-window 
value.  It  is  often  defined  to  be  a  lambda  expression 
that  sets  *currcnt-display-window*  to  a-display- 
window  value  and  returns  that  value. 

A  call  to  get- current- display- window  will  return  a- 
display- window  derived  from  *  current- display- 
window*,  or  will  signal  an  error  if  no  window  is 
obtainable  in  this  way. 

•PLAYBACK-DISPLAY-WINDOW : 
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GET-PLA^'BACK-DISPLAY-WINDOW:  *  Playback- (hspluy-mndoxv*  and  gti-playback-display- 

windoxr  are  analogous  to  *cvrrcn(-display-wvidow* 
and  gei-currtnf-display-window,  except  that  the  win¬ 
dow  reuirned  is  used  only  by  a  few  functions:  in  fact, 
at  the  moment,  only  by  the  playback- display  fuucUou. 
However,  the  *cxiTrcnt-display-window*  is  usually 
defined  in  terms  of  the  *  playback- dxsplay-xvindow* , 

HAS-PARENT:  A-display-xrindow  is  associated  with  a-display,  the  has-partni  attribute  of 
the  window.  Drawing  in  the  window  actually  draws  in  its  parent  display. 

If  a  window  is  created  with  another  window  as  a  parent,  the  has-parcnt 
attribute  is  changed  to  ecjunl  the  parent  display  of  the  parent  window,  and 
the  has-sizes.  has-zooxas,  has-orientation,  has-origiTiSf  has-uppcr-lcjt,  and 
has-lower-riyhi  parameters  are  adjusted  accordingly. 

H^S-SIZES.  The  window  appears  to  be  a  rectangular  display  with  sizes— 

(n_\size  n^ysize). 

This  is  ma])ped  onto  a  bo.\  in  the  window's  parent  (see  has- orientation,  has- 
zooms.  etc.  below). 

The  coordinate.s  of  a  window  are  like  those  of  a  display.  The  upper  left  pixel 
of  the  window  has  a  center  with  zero  coordinates.  The  X  ccK:)rdinates  of  this 
pixel  lie  in  the  range  from  -0.5  to  -fO.5.  Similarly  for  the  Y  ccx)rdinates.  If 
n_xsize  and  n^ysize  are  integers,  the  lower  right  pixel  of  the  window  has  a 
center  with  ccx)rdinates  (n_xsize— 1  n_ysize— 1),  X  ccK:)rdinates  in  the  range 
from  n_xsize— 1.5  to  n_xsize— 0.5,  and  Y  coordinates  in  the  range  from 
n_ysize— 1.5  to  n_ysize“0.5. 

Any  line  written  into  the  w'indow  that  would  be  partly  outside  the  window  is 
clipped:  the  parts  outside  are  not  drawn.  Similarly  any  image  written  into 
the  wdndow  is  clipped:  the  parts  outside  are  not  drawn.  However,  any  char¬ 
acter  written  into  the  window  is  omitted,  and  not  written  at  all,  if  any  part 
of  it  w^ould  lie  outside  the  window. 

HAS-ORIENTATION: 

HAS-ZOOMS: 

HAS-UPPER-LEFT: 

HAS-LOWER-RIGHT: 

HAS-ORIGINS:  A-display-xvindoxv  maps  onto  a  box  in  its  parent  display.  To  specify  the 
box  one  typically  gives  its  upper  left  corner  and,  indirectly,  its  sires.  The 
sizes  of  the  box  are  the  products  of  the  sizes  of  the  window  and  the  rooms 
of  the  window,  and  it  is  these  latter  two  quantities  that  are  given  directly. 

The  orientation  of  the  window  in  the  box  is  a  symbol  that  tells  how  to 
rotate  the  window  to  fit  it  into  the  box.  LeJt-roiaU^  right-roiaiCj  and  top- 
roiate  mean  to  rotate  the  window  90  or  180  degrees  so  that  the  window’s 
bottom  becomes  the  left,  right,  or  top  of  the  box.  M7  (the  default)  means 
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not  to  rotate  the  window  at  all. 

The  orientation  may  also  be  left-mirror,  right-mirror,  or  top-mirror  to 
specify  that  the  left  and  right  of  the  window  are  interchanged  before  it  is 
rotated;  or  the  orientation  may  be  just  plain  mirror  to  interchange  left 
and  right  without  rotating. 

The  zooms  are  the  ratios  of  the  sides  of  the  window  to  the  sides  of  the  box 
they  are  mapped  onto.  Thus  n^xzoom  is  the  length  of  the  side  of  the  box 
that  the  bottom  (or  top)  of  the  window  is  mapped  onto,  divided  by 
n_xsize.  Similarly  for  n^yzoom,  the  left  (or  right)  of  the  box,  and  n^ysize. 

The  has-vpper-left  and  has-lower -right  attributes  give  the  upper  left  and 
lower  right  corners  of  the  box  onto  which  the  window  is  mapped.  The 
h(t!i-origi))s  attribute  gives  the  point  in  the  box  that  the  upper  left  pixel  of 
the  window  is  mapped  onto.  If  the  orientation  is  nil,  then  — 

ji_\upper-left  —  0.5  =  n_xorigin  -f  (—  0.5)  *  n_xzoom 

since  the  left  edge  of  the  upper  left  pixel  of  the  window  has  x  coordinate 
—0  5.  while  the  left  edge  of  the  box  has  x  coordinate  n_xupper-left— 0.5.  A 
similar  relation  holds  for  the  y  coordinate.  The  relations  for  the  low'er 
right  corner  of  the  box.  and  for  other  orientations,  can  be  derived  simi¬ 
larly,  remembering  that  the  right  of  the  window  has  x  coordinate 
n_x$ize— 0.5.  Thus,  for  example,  if  the  orientation  is  rotate-left,  then  — 

n_xupper-left  —  0.5  =  n_xorigin  —  (n_ysize  —  0.5)  *  n_yzoom 

since  the  rotation  puts  the  origin  near  the  upper  right  corner  of  the  box 
and  also  exchanges  the  X  and  Y  axises. 

Notice  that  the  numbers  n_xupper-left,  n_yupper-left,  n_xlower-right, 
n_ylower-right,  n_xorigin,  n^yorigin,  n^size,  n^ysize,  n^xzoom,  and 
n_yzoom  may  all  be  non-integer  floating  point  numbers.  In  this  respect 
a- display- window  is  not  like  a-display,  for  the  sizes  of  the  latter  must  be 
integers. 

If  the  has-parent  given  to  create  a  window  is  itself  a- display- window,  the 
corners,  origins,  zooms,  and  orientation  are  all  specified  relative  to  the 
parent  window,  but  are  converted  to  be  relative  to  the  parent  display  of 
that  window'  when  the  has-parent  attribute  is  converted  to  be  that  parent 
display  (see  HAS-PARENT  above). 

If  has-origins  is  given,  neither  has-upper-left  nor  has-lower-right  may  be 
given.  It  is  illegal  to  give  all  four  of  the  attributes  has-upper-left,  has- 
lower-right,  has-sizes,  and  has-zooms. 

DEFAULT  FOR  HAS-SIZES: 

DEFAULT  FOR  HAS- ZOOMS: 

DEFAULT  FOR  HAS-UPPER-LEFT:  If  a  w  indow  is  created  with  a  prototype,  as  in-- 
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((hdisplay-wiiulou'  (gef’ current- display- windou) 

has-origins  '(10  10)  has-sizes  *(128  128)) 

llie  lws-origin$^  has-vpper-left,  luis-lower-riglit,  has- 
sizes.  and  h(is-2ooins  attributes  are  not  inherited  from 
the  prototype,  unless  none  of  these  attributes  are  given, 
and  the  has-parent  and  has- orientation  attributes  are 
also  not  given.  (Giving  a  nil  value  is  equivalent  to  not 
giving  n  value  for  any  of  these  attributes  except  has- 
orientation.) 

Except  in  this  case,  has-upper-left  defaults  to  ’(0.0  0.0)  if 
neither  it  nor  lias-origin  nor  /i05-/ou^er-r7^/i/  is  given; 
has-zooiiis  defaults  to  ’(1.0  1.0)  unless  it  can  be  com¬ 
puted  because  has-sizes,  has-upper-left,  and  has-lower- 
right  have  all  been  given;  and  lastly,  has-sizes  defaults, 
if  it  cannot  be  computed,  to  the  largest  value  which  will 
allow  the  window  to  fit  inside  its  has-parent. 

WINDOW  PCI. NTS- 

R\S*TR.-\NSFORM: 

DWPT.:  A  window  point  is  a  point  in  the  coordinate  system  of  a-display-\mn(lou\  The 
window  coordinate  system  places  the  point  (0  0)  at  the  center  of  the  upper  left 
pixel  of  the  window,  and  increases  the  X  and  Y  coordinates  by  1  as  one  moves  1 
pixel  right  or  down.  The  X  axis  is  horizontal  and  the  Y  axis  vertical. 

A  window  point  can  be  specified  directly  as  a  pair  of  numbers  (either  fixnum^s 
or  flonuni^s). 

A  window  point  can  also  be  specified  as  a  point  in  the  sense  of  the  ANALYTIC 
GEOMETRY  package  (actually  a-vector  value),  in  which  case  it  is  transformed 
into  the  window  coordinate  system  by  the  value  of  the  window’s  has-iransform 
attribute,  which  is  a- transform  value.  A  nil  has-transform  value  is  considered  to 
be  equivalent  to  the  unit  transform  of  2  dimensional  space.  See  the  ANALYTIC 
GEOMETRY  package  for  more  details. 

A  dwpt^  argument  is  a  window  point:  either  a  list  of  two  numbers  or  a-vector 
value.  The  later  is  converted  into  a  list  of  two  numbers.  If  a  window  point  is 
stored  in  a- display- window,  it  is  always  stored  in  the  form  of  a  list  of  two 
numbers,  and  will  be  read  in  that  form. 

HAS-CURSOR:  The  cursor  is  a  window  point.  It  acts  as  an  offset  to  the  position  where 
objects  (e.g.  lines  and  images)  are  drawn  in  the  window. 

The  has-cursor  attribute  can  be  self  and  so  can  the  its  individual  coordi¬ 
nates.  It  may  be  seif  to  a  window  point  (see  WINDOW  POINT  above). 

The  cursor  defaults  to  (0  0). 
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H.\S-L1KE-PLANE: 

R\S-TEXT.PLANE: 

RAS- AREA-PLANE: 

RAS-PLANE:  Lines  are  drawn  by  default  in  the  bitgraph  plane  specified  by  xjine-plane, 
which  is  the  Z  ccx)rdinate  of  the  plane.  This  attribute  may  be  5e// anytime. 
It  may  be  sefj  to  the  name  of  a  plane  (either  a  symbol  or  a  symbol/integer 
pair*  see  BITGRAPH  PL.ANE  NAX4ES  under  Q-display),  in  which  case  the 
name  is  converted  to  the  plane  Z  coordinate  before  it  is  stored. 

Characters  are  drawn  similarly  in  the  bitgraph  plane  specified  by  x_text- 
plane,  and  areas  are  filled  in  the  bitgraph  plane  specified  by  x_area-plane 

The  has-plnne  attribute,  when  scif^  sets  all  three  of  the  other  plane  attri¬ 
butes  to  the  same  value.  Has-plane  may  be  read  without  error  only  if  all 
three  of  the  other  plane  attributes  have  the  same  value,  which  is,  of  course, 
the  value  read. 

The  ha^-liiie-plnne.  Iwfi-area-plave,  and  has-texf-plave  attributes  default  to 
the  value  0  if  the  window's  parent  display  has  a  non- mV  has-bitgraph-plave^ 
attribute:  or  to  the  value  mV  otherwise. 

RAS- 1 NTENS 1  T\'-  .AR  R  A^' : 

RAS-Bl  TGRAPH- PLANES : 

RAS-BITGR.APH-.ARR.AY: 

RAS-BITGRAPH-PR0GRAA1S: 

RAS-DEVICE: 

RAS-FILM: 

RAS-RANGE: 

HAS-PRIMARY-COLORS: 

HAS-COLORS: 

RAS-SCALES: 

HAS-MAP: 

RAS-PLANE- TYPES:  These  are  all  attributes  of  the  has-parent  of  a- display •  window ^  but  we 
frequently  abuse  language  and  speak  as  if  they  were  the  attributes  of 
the  window.  They  are  not,  and  programs  cannot  treat  them  as  such. 
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(a-plane-type  lias-color  ’s_colorl  [SKETCH  Type  Macro] 

[liiis-fill-pafferv  ’ubarjll-pattern] 

[has-lnie-type  ’s_line-typej 
[lias-liii€-tindlli  ’njine- width] 

[lias-cliaracler-font  ’s_character-font] 

Ihos-cliaracter-sizes  ’(n_xcharacter-size  n_ycharacter-size)j) 

[Argument  Prefix] 
[SKETCH  Type  Object] 


plt_ 

a-plane-type 


(has-color  'pll_display) 
(has-fill-pattern  ’plt_display) 
(has- line- type  ’pJt_display) 
(has-line-width  ’plt^display) 
(has-character-font  ’plt_display) 
(has-character-sizes  ’pli_display) 


(SKETCH  Attribute  Macro] 
[SKETCH  Attribute  Macro] 
[SKETCH  Attribute  Macro] 
[SKETCH  Attribute  Macro] 
[SKETCH  Attribute  Macro] 
[SKETCH  Attribute  Macro] 


USE:  A-plaii€‘iype  parameterizes  a  bitgraph  plane.  It  specifies  color,  fill  pattern  (a  bit- 
graph  array)  for  filling  areas,  line  type  (solid,  lovg-daslied,  etc.),  normal  line  width, 
cliaraclcr  font  (display,  iiines-roinan,  etc.),  and  normal  character  sizes. 


ll^S*CC)LOR:  .A  symbol  naming  the  color  of  the  plane’s  pixels:  e.g.  red.  When  the  plane  is 
used,  the  color  must  appear  in  the  display’s  has-colors  list  (which  is  inher¬ 
ited  from  the  display’s  map). 


A  nil  value  is  equivalent  to  while. 

HAS-FILL-PATTERN:  A  bitgraph  array  which  is  used  to  fill  areas.  This  two  dimensional 
array  of  a-ubirs  is  replicated  starting  in  the  lefthand  corner  of  a 
display  to  make  a  mask  that  covers  the  entire  display.  When  an 
area  in  the  display  needs  to  be  filled,  the  pixels  in  the  area 
corresponding  to  one  bits  in  this  mask  are  turned  on. 


A  nil  has-fill-pattern  attribute  value  is  equivalent  to  an  array  with 
all  its  bits  on,  giving  a  solid  area  fill. 

HAS-LINE-TYPE:  This  is  a  symbol  chosen  from  the  list— 

solid 

dotted 

long-dashed 

short-dashed 

dot-dashed 

It  describes  the  type  of  line  drawn  by  the  display-lines  function. 


A  nil  value  is  equivalent  to  solid. 

HAS-LINE-WIDTH:  Specifies  the  normal  value  for  a  line’s  width  in  pixels,  for  lines  drawn 
by  the  display-lines  function.  Fractional  widths  are  possible:  the 
nearest  available  width  is  used.  The  actual  line  width  used  to  draw  a 
line  is  the  product  of  this  number  and  the  line  width  specified  by  the 
display-lines  function  that  draws  the  line. 
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A  ////value  is  e(|uivalenl  to  1.0. 

H.^S-CH.\EACTER-FONT:  The  style  of  tl»e  character  set  used  by  display-print  and  related 

function^.  See  the  has-Jont  attribute  of  a-charactcr-sei  in  the 
BITGR.XPH  .4RRAYS  package. 


A  nil  value  is  equivalent  t^o  display. 

R^S-CH.-\RACTER-SIZES:  N_.\ch  a  racier- size  and  n^ycharacter-size  are  the  width  and 

height  in  pi.xels  of  a  box  into  which  each  character  is  to  fit.  The 
character  set  choosen  for  use  by  a  display-print  or  similar  func¬ 
tion  is  the  largest  whose  characters  will  fit  in  the  box,  in  a  sense 
we  will  now  describe. 

N_vcharacter-size  is  actually  the  distance  between  successive 
lines  of  text,  and  must  be  somewhat  greater  than  the  actual 
height  of  the  characters.  N_A*character-size  is  an  upper  bound 
on  the  probable  average  horizontal  spacing  between  characters, 
for  capitalized  English  words.  For  variable  width  fonts,  words 
with  lower  case  letters  generally  have  characters  somewhat 
closer  together  than  n_xcharacter-size  would  indicate,  while 
strange  words  like  HMMX'CvtNl  might  have  characters  farther 
apart  than  x_character-size  would  indicate.  See  HAS-SIZES 
under  a-character-sei  for  more  details.  The  character  set  is 
actually  found  using  the  find-cliaracter-set  function. 

The  actual  character  sizes  used  to  select  a  character  set  are  the 
product  of  these  sizes  and  the  character  size  number  specified  by 
the  display-print  or  similar  function  that  draws  the  characters, 


“bitgraph  programs” 

(w  (n_xsize  n_ysize)  (n_xorigin  n_jorigin) 

(n_xzoom  n.yzoom)  s.orientation  <statement>  ...) 
(t  |n_character-size] 

[s^horizontal-adjust]  [s_vertical-adjust] 

(s.orientation)  (n_xorigin  n.yorigin)  s/t_string  ...) 

(1  [n^width)  (n_xorigin  n_yorigin) 

[(n_x  n_y)]  ...  |ni7]...  [sar_array]  ...) 

(f  (n_xorigin  n_yorigin)) 


(SKETCH  Term] 
[Bitgraph  Program  Window] 

[Bitgraph  Program  Statement] 

(Bitgraph  Program  Statement] 
[Bitgraph  Program  Statement] 


VALUE:  A  bitgraph  program  is  a  list  of  bitgraph  program  windows.  Each  bitgraph  pro¬ 
gram  window^  consists  of  a  list  with  some  window  parameters  followed  by  bit- 
graph  program  statements.  The  statements  are  of  three  types:  text  statements 
output  text,  line  statements  output  lines,  and  fill  statements  fill  areas  (respec¬ 
tively  the  t,  /,  and  /statements  above). 


The  window  parameters  define  the  sizes,  zooms,  origins,  and  orientation  of  the 
window':  see  a-display-window. 


See  display-text  for  text  statement  parameters;  display-lines  for  line  statement 
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parameters:  and  Jill-display-areo  for  fill  statement  parameters. 

(check-bitgraph-program-syntax  M.program)  [LISP  Function] 

SIDE  EFFECT:  Cliecks  the  bitgraph  program  for  syntax  errors,  and  calls  error  if  any  are 

found. 

(dear-display  ps^backgroundj  pdwin_window])  [LISP  Function] 

(dear-intensity  |’s_backgioiindj  |‘dwin_window])  [LISP  Function] 

(dear-bitgraph  |’bpn_planej  pdwm.window])  {LISP  Function] 

WHERE:  S_backgrouncl  must  be  a  symbol  naming  a  has-color  color  of  dwin_window 
(default  is  black). 

Bpn_plane  mnv  be  nil  or  omitted  to  specify  the  set  of  all  bitgraph  planes. 

Dw  in_windo\\  defoiills  to  the  value  of  the  value  of  {get-cxirrent-display-windoxc). 

Nil  arguments  are  ignored  (so  any  argument  may  be  nil). 

SIDE  EFFECT:  Clears  the  intensity  and  bitgraph  plane  parts  of  a  display  window. 

Cleiir-displuti  clears  everything;  cleor-infensity  just  clears  the  intensity 
array;  while  clear-bitgraph  just  clears  one  or  all  bitgraph  planes. 

It  is  an  error  to  try  to  clear  a  bitgraph  plane  if  dwin_window  does  not 
cover  its  parent  display  entirely  and  the  parent  display  has  bitgraph  pro¬ 
grams. 

The  intensity  array  is  set  to  a  specified  value,  s^background,  when  it  is 
cleared. 

(dose-display  |dwin_display])  [LISP  Function] 

WHERE:  Dwin.window  defaults  to  the  value  of  {get-current-display-window). 

SIDE  EFFECT.  Releases  the  resources  of  the  parent  display  of  dwin^window.  These 
resources,  things  like  the  display  monitor  hardware  and  communications 
channels  to  that  hardware,  are  allocated  the  first  time  the  display  b 
flushed.  After  closing  the  display,  the  resources  will  be  reallocated  the 
next  time  the  display  is  flushed. 
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(compose-display-orientations  s.first  ’s^second)  [LISP  Function] 

REXrRNS:  Returns  the  display  orientation  that  is  the  composition  of  the  display  orienta¬ 
tion  s_first  followed  by  the  display  orientation  s_second.  Display  orientations 
are  the  possible  values  of  the  has- orientation  attribute  of  a-d\splay-xvindovi\ 

(display-bitgraph  iibar.array  ’s/Lname  ['d\vin_window|  [LISP  Function] 

['d\vpt_upper-Ieft]  [has- zooms  ’(n_xzoom  n_yzoom)] 

\has-sizes  '(n_>csize  n_ysize)] 

[has-orientation  *s_orientation]) 

(display-bitgraph  ’ubar.array  ^(s/Lname-1  ...)  [’dwin_window]  [LISP  Function] 

(’cl\vpt_upper-left]  [has-zooms  ’(n_xzoom  n_yzoom)] 

[has-stzes  '(n_xsize  n_ysize)] 

[has-orientation  ’s_orientation]) 

USE  ONLY  WHEN:  Displays  have  only  bitgraph  arrays  and  do  not  have  bitgraph  pro¬ 
grams. 

The  display-bitgraph  function  is  an  anachronism  that  should  be 
replaced  where  possible  by  calls  to  display-text,  display- lines,  and  fill- 
illsplay-area,  because  the  latter  are  output  resolution  independent, 
while  display-bitgraph  depends  upon  the  application  knowing  the  reso¬ 
lution  of  the  output  display. 

WHERE:  The  dwin_window,  dwpt_upper-left ,  n_xzcx>m,  n_yzoom.  n_xsize,  n^ysize  and 
s_orientation  arguments  are  passed  to  the  7iew-ivindou-  function  to  get  a  win¬ 
dow  referred  to  as  dwin_window  below. 

The  zooms  of  dwin_window  relative  to  its  parent  display  must  be  1.0.  The  pix¬ 
els  of  dwin_window  must  be  exactly  aligned  with  the  pixels  of  its  parent 
display. 

If  dwin.window  has  a  bitgraph  array,  each  s/Lname  is  a  bitgraph  plane  name 
of  a  plane  in  dwin_window  into  which  a  plane  in  ubar_array  maps;  or  s/Lname 
may  be  nil  to  indicate  a  plane  in  ubar_array  is  not  to  be  merged  into 
dwin_window.  The  planes  of  ubar_array  correspond  to  the  Z  coordinates  of 
ubar.array,  and  these  taken  in  order  (0,  1,  2,  ...)  correspond  to  the  elements  of 
the  list  of  s/Lnames’s  (if  there  is  only  one  name  it  may  be  given  directly, 
instead  of  as  in  a  list). 

If  dwin_window  has  no  bitgraph  array,  but  only  an  intensity  array,  each 
s/Lname  is  just  a  symbol  naming  a  color  in  the  has-colors  list  of  dwin^window; 
or  s/Lname  is  ni7  to  indicate  a  plane  in  ubar.array  is  not  to  be  merged  into 
dwin.window. 

SIDE  EFFECT:  Copies  the  information  in  ubar_array  into  the  bitgraph  array  of 
dwin.window,  if  d\vin_window  has  one,  or  the  intensity  array  of 
dwin_\vindow  otherwise. 

The  merging  is  done  just  as  it  would  be  by  merge-display  if  ubar_array 
were  an  attribute  of  a-display.  If  dwin^window  has  a  bitgraph  array, 
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iibar_array  is  meigoci  inio  that,  if  clwin.window  has  an  intensity  array, 
but  no  bitgraph  array,  nbar^array  is  merged  into  the  intensity  array.  It 
is  not  an  error  for  cl\vin_\\ iiidow  to  have  bitgraph  programs,  but  they  will 
be  unefl'ectecl  by  (li^pltnj-bitijraph. 


(display-image 


'  a r.a  v  r  a  \  [  'cl  w i  n_\v  i  n  cl  ow  ] 

[  dwpt_upper-leftj  \h(h^-zooms  *(n_xzoom  n_yzoom)] 
\lws-s7ze^-  ’(n_\size  n_ysize)] 

\ha{i-ori€vta!ioii  s.orientation] 

\h(is-bov7ids  ’(n.black  n_\vhite)] 

[/?n5-6oi/T?r/vS ’(n_bouncl-l  [— ]  s_scale-l  ...  n_bound-N)] 
|/in6-T??76S7/?/;  '5_niissing-color' 

\hcs-low  ’s.low-colorj 
[hai^-high  ’s.high-color; 

[hos-covfrasff:  ’(x^xcontra.st  x_ycontrast)] 
[do-pseudocolor  "g_pseii(locolor-switch]) 


(LISP  Function] 


WHERE;  The  d\vin_windo\v,  dwpt^iipper-left.  n_xzcK>m,  n_yzoom,  n_xsize,  n_ysize  and 
s_orientation  arguments  are  passed  to  the  new-wiiidow  function  to  get  a  win¬ 
dow  relen  ed  to  as  (lwin_\N  indow  below. 


X_xcontvast  and  x_yconirasl.  if  given,  must  be  >  0. 

S_missing- color  delaulis  to  red. 

There  are  two  forms  for  the  litis-bouiids  argument.  The  simple  form  (n_black 
n_white)  specifies  the  range  of  image  values  which  will  map  onto  the  display’s 
gray  scale  (or  pseudocolor  scdAe  with  the  do-pseudocolor  option). 

If  the  has-bounds  argument  is  tu7,  n_black  and  n_white  default  to  the  minimum 
and  maximum  value  in  ar_image. 

The  more  complex  form  of  the  has-bounds  argument  gives  a  list  of  bounds  and 
between  each  the  name  s^scale  of  a  scale  that  is  used  to  map  the  image  values 
between  the  bounds.  Each  s^scale  names  a  vector  that  is  associated  with  two 
bounds,  a  lower  bound  and  an  upper  bound.  An  image  value  that  b  greater 
than  or  equal  to  the  lower  bound,  and  less  than  the  upper  bound,  is  converted 
to  a  vector  subscript  by  the  formula 

{floor  (  (image  value  —  lower  bound)  vector  size) 

/  (upper  bound  —  lower  bound)) 

This  subscript  indexes  a  vector  element  which  yields  a  value  for  an  intensity 
array  pixel. 

The  scales  are  defined  by  the  luis-scales  attribute  of  the  window’s  parent,  which 
is  inherited  from  the  parent’s  display  map.  See  HAS-SCALES  under  a-display- 
map  for  the  scales  available  when  the  standard  display  map  is  in  use. 

In  the  case  of  the  complex  has-bovnds  list,  the  bounds  must  be  in  ascending 
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order.  However,  any  bound  may  be  nil.  If  the  first  bound  is  ntl,  it  will  be 
replaced  by  the  minimum  of  all  the  image  elements  and  the  first  non-«// bound 
Similarly,  if  the  la^t  bound  is  ml,  it  will  be  replaced  by  the  maximum  of  all  the 
image  elements  and  the  last  non-nil  bound.  If  any  other  bounds  are  nil,  they 
will  be  replaced  in  a  fashion  that  will  make  all  the  scales  between  each  pair  of 
non- nil  bounds  appear  to  be  concatenated. 

AV/ bounds  may  be  completely  omitted  from  the  list.  Thus  the  bounds  list- 

-0.5  black  red  99.5 

effectively  makes  a  new  17  interval  scale  by  concatenating  the  1  interval  scale 
block  with  the  16  interval  scale  red. 

If  a  sealers  immediately  preceded  by  a  —  in  the  has-bounds  list,  the  order  of  the 
values  in  the  scale  is  reversed:  e.g.  a  black  to  white  scale  becomes  a  white  to 
black  scale. 

SIDE  EFFECT:  Displays  the  image  in  dwin_window.  If  the  image  is  too  small,  it  is  placed 
in  the  upper  left  corner  of  the  w’indow,  and  if  too  large,  only  the  upper  left 
corner  of  the  image  is  displayed. 

If  the  window  has  zooms  that  are  not  equal  to  1.0,  each  pixel  in  the 
w'inclow's  parent  display  is  given  the  value  of  the  image  pixel  determined 
by  mapping  the  display  pixel's  coordinates  back  to  image  pixel  coordinates 
and  rounding  to  the  nearest  image  pixel. 

If  the  lias-contrasts  argument  is  given,  the  image  will  have  the  average  of 
a  rectangle  of  size 

(2  *  x_xcontrast  -HI  2  *  x_ycontrast  -H  1) 
subtracted  from  each  element  by  the  con^ra5/-o/ function. 

The  has-missing  argument  specifies  the  color  in  which  missing  values  will 
be  displayed  (default  red).  Has-low  specifies  the  color  in  which  values 
below^  the  lowest  lias-bound  bound  will  be  displayed.  If  has-low  is  nil  (the 
default),  values  lower  than  the  lowest  bound  will  be  treated  as  equal  to  the 
lowest  bound.  Similarly,  has-high  specifies  the  color  in  which  values  equal 
to  or  above  the  highest  has-bound  bound  will  be  displayed.  If  has-high  is 
nil  (the  default),  these  values  are  treated  as  being  just  below  the  highest 
bound. 
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(display-lines  ;clwin_winclow]  [n«width]  [LISP  Function] 

jbpn^plane-  jtrans.transform) 

|dwpt_pointj  ...  [tuVj  [[— ]  ar_array]  ...) 

\MiERE;  Dwin_window  defaults  to  the  value  of  {get’Cvrrent’disploy-window)^  n.width 
defaults  to  1.0,  bpn_plane  defaults  to  the  has- line-plane  attribute  of 
d\vin_windovv,  and  trans_transform  defaults  to  the  lias-transform  attribute  of 
dwin_window. 

Nil  arguments  before  the  first  dwpt_point,  — ,  or  ar_array  are  ignored. 

SIDE  EFFECT:  Draws  in  bpn_plane  a  sequence  of  straight  lines  connecting  points  in  the 
display  window.  Each  point  is  either  an  argument  (e.g.  dwpt_point),  or  is 
a  row'  in  an  array  argument  (e.g.  ar_array)  whose  first,  second,  and  third 
columns  are  the  X,  Y,  and  Z  coordinates  of  the  points,  respectively  (there 
may  be  no  Z  coordinate,  or  even  no  Y  coordinate).  The  points  defined  by 
an  array  are  transformed  by  trans_transform  xniless  the  array  is  pro¬ 
ceeded  by  a  in  which  case  they  are  not  transformed.  Any  dwpt_point 
points  that  are  n-uec/or  objects  are  also  transformed  by  trans_transform. 

A  nil  argument  separates  a  preceeding  sequence  of  lines  from  a  following 
sequence.  Thus  many  different  sequences  can  be  displayed  by  one  call  to 
display-lines.  An  ar_array  point  with  a  missing  coordinate  separates  line 
sequences  like  the  nil  argument. 

Line  sequences  are  displayed  by  dragging  a  circular  dot  of  size  determined 
by  n_width  in  straight  lines  between  line  sequence  points.  If  a  line 
sequence  consists  of  a  single  point,  at  single  dot  is  drawn  at  that  point. 

All  line  end  points  are  offset  from  the  window  origin  by  the  window  cursor 
position. 

The  boundaries  of  the  window  clip  the  lines.  The  line  end  points  need  not 
lie  inside  the  window. 

(dbplay-text  (’xjine-length  [’(n_xorigin  n_yorigin)]  [LISP  Macro] 

pbpn.planej  [’s_adjust ...]  [’n^izej  [’s_orientation]  (’dwin^window)) 
g_j5tatement ...) 

(display-print  ’g_value  [’(n_^origin  n«yorigin)  [LISP  Function] 

[*bpn_plane]  [*s_adjust  ...]  [’iLJsize]  [’s_orientation]  [’dwin_window]) 
(display-patom  ’g^value  [’(n_xorigin  n^yorigin)]  [LISP  Function] 

[’bpn_plane]  [’s_adjust  ...]  [’n_size]  [’s^orientation]  [’dwin^window]) 
(display-pretty-print  ’x_line-length  ’g^value  [LISP  Function] 

[’(n_j(origin  n«yorigin)]  [*bpn«plane]  [’s.adjust ...]  [’n^ize] 
[’s_orientation]  [*dwin«window]) 

(mak e-display-text-string  ’x^tring-size-in- bytes)  [LISP  Function] 

WHERE:  Dwin_window  defaults  to  the  value  of  {get-current-display-window)^  n_xorigin 
and  n^origin  default  to  0.0,  n_size  defaults  to  1.0,  and  s_adjust  and 
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s.orientation  default  to  nil.  Bpn_plane  defaults  to  the  has-Uxt-plant  attribute 
of  dwin_windo\v. 

Nil  arguments  are  ignored. 

SIDE  EFFECT:  Text  is  drawn  at  the  origin  location  in  bpn.plane.  The  origin  actually 
used  is  that  given  by  (n^xorigin  n.yorigin)  displaced  by  the  window  cur¬ 
sor. 

The  text  is  first  written  into  a  string  buffer.  The  result  may  be  1  or  more 
lines  (the  last  line  need  not  end  with  a  line  feed).  Display-print  writes  as 
print\  display-pat oin  as  palovi]  and  display-prctty-print  as  pretty-print. 
During  the  execution  of  display- pretty-print  the  LISP  global  variable 
Uinc-length*f  the  line  length  used  by  pretty-print^  is  bound  to  x^line- 
length. 

Display-text  is  a  macro  which  (1)  binds  a  port  that  writes  into  a  string  to 
the  normal  output  port,  popart,  (2)  binds  x_Iine-length  to  *line-length*  for 
use  by  pretty-print,  (3)  evaluates  and  remembers  s_adjust,  n_size, 
s_oi ientation,  and  dwin_window.  (4)  executes  the  body:  g^tatement  .... 
and  (5)  writes  the  the  string  into  dwin_window  using  the  remembered 
s_adjust,  n^jsize,  and  s_orientation. 

After  the  text  is  written  into  the  string  buffer,  the  font  and  size  of  the 
characters  are  determined.  The  normal  character  size  for  the  bit  plane 
being  used  is  multiplied  by  n^ize  to  determine  character  size.  Then  the 
width  and  height  of  the  text  in  pixel  positions  are  computed.  These  is 
used  to  form  an  imaginary  box  around  the  text.  The  text  lines  arc  then 
adjusted  in  the  box  according  to  some  of  the  s.adjust  parameters  (as 
described  below).  Lastly,  the  box  is  positioned  in  the  display  window 
according  to  the  origin  position,  s_adjust,  and  s_oricntation  parameters, 
and  the  text  is  drawn. 

S_ADJUST:  The  s_adjust  parameters  control  the  positioning  of  lines  within  the  text  box, 
and  the  positioning  of  the  box  relative  to  the  origin.  The  possible  s_adjust 
values  are— 
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left 

The  origin  is  placed  just  to  the  left  of  the  bo.\. 

The  lines  of  text  with  the  least  amount  of  blank  space  at 
their  left  are  left  justified  in  the  box.  The  lines  with  the 
next  least  amount  of  blank  space  at  their  left  have  their 
first  non-blank  character  printed  directly  under  the  charac¬ 
ter  in  the  same  column  of  the  first  line  above  them  that  has 
already  been  justified,  if  any,  or  the  first  already  justified 
line  below  them  if  there  is  no  such  line  above.  And  so 
forth,  until  all  lines  are  justified. 

right 

Like  left  but  to  the  right  instead  of  the  left. 

— 

If  neither  left  or  right  is  given,  each  line  has  blank  space  at 
its  beginning  and  ending  removed,  and  is  then  centerred  in 
the  box.  The  origin  is  placed  at  the  center  of  the  box  in  the 
horizontal  dimension. 

under 

The  origin  is  placed  just  under  the  box. 

over 

The  origin  is  placed  just  over  the  box. 

— 

If  neither  xinder  or  over  is  given,  the  origin  is  placed  at  the 
center  of  the  box  in  the  vertical  dimension. 

N_SIZE:  This  parameter  is  a  number  which  multiplies  the  normal  character  size  for  the 
bitgraph  plane  in  which  the  text  is  placed.  Both  horizontal  and  vertical  sizes 
are  multiplied  by  n_size.  The  character  set  actually  used  is  the  largest  available 
whose  sizes  do  not  exceed  those  requested.  (Acutally,  the  horizontal  size  is  made 
as  large  as  possible  first,  and  then  the  vertical  size.) 

S.ORIENTATION:  This  is  one  of  the  values— 


nil 

Uft-rotaic 

iop-roiaic 

right-rotate 


mirror 

left-mirror 

top-mirror 

right-mirror 


The  entire  text  is  rotated  as  indicated  around  the  origin  position.  Nil 
means  to  do  no  rotation;  top-rotate  means  to  rotate  180  degrees  to 
make  the  bottommost  part  of  the  characters  near  the  top  of  the 
display. 


The  mirror  forms  do  not  cause  the  characters  to  be  mirror-imaged,  nor 
do  they  reverse  the  order  of  the  characters  in  the  text.  But  they  do 
switch  which  side  of  the  text  the  origin  is  on,  left  or  right,  when  viewed 
after  any  rotation.  An  attempt  is  also  made  to  keep  the  amount  of 
blank  space  between  the  text  and  the  origin  the  same  as  it  would  have 
been  if  the  text  had  not  been  mirrored. 


The  orientation  of  the  text  specified  by  s^orientation  is  composed  with 
any  orientation  specified  for  the  window  in  which  the  text  is  displayed 
to  get  the  orientation  actually  used  for  display  of  the  text. 
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MAJ\E-D1SPLAY- TEXT-STRING:  The  string  used  by  display-print  etc.  is  initialized  when  the 

system  is  loaded  and  has  a  size  of  16384  bytes.  A  call  to 
make-display-texl-string  will  create  a  new  string  of  a 
different  size  for  the  use  of  display-print  etc.  This  is  useful 
only  if  the  old  string  is  too  small. 

(ex pose- display  [’x_count]  [’dis/dwin_display])  [LISP  Function] 

WHERE:  Dis/d\vin_display  defaults  to  the  value  of  (gel-currct)f-di$play-window). 

X_count  defaults  to  1. 


AV/  arguments  are  ignored  (so  any  argument  may  be  niT). 

mi 

SIDE  EFFECT:  Flushes  dis/dwin_display  as  per  flush- display,  and  then  takes  x^count 
identical  pictures  of  the  current  state  of  the  display.  The  has-dcvice  attri¬ 
bute  value  determines  the  procedure  for  doing  this.  A  timer  value  is  used 
in  the  flush  which  allows  enough  time  for  the  camera  to  take  the  pictures, 
and  expose-display  returns  before  the  camera  is  done. 

The  pseudocolor  map  in  the  display  hardware  may  be  changed  tem¬ 
porarily  while  the  picture  is  being  taken,  causing  the  picture  to  look 
diflerent  temporarily  on  any  television  monitor.  This  is  done  to  compen¬ 
sate  for  differences  between  the  television  monitor  and  the  camera  plus 
film,  so  that  after  the  film  is  developed,  it  will  look  the  same  as  the  televi¬ 
sion  monitor  normally  looks. 

The  has-camera-parameters  attribute  of  the  display  map  selected  by  the 
display’s  has-map  and  has-film  attributes  will  be  used  to  set  the  camera 
parameters.  See  HAS-CAMERA-PARAMETERS  under  a- display-map. 


(find-display-map  ’(s_map-name  [s_monitor  ...])) 
(find-display-map  ’s_map-name) 
(find-display-maps  ’(s_map-name  |s_monitor  ...])) 
(find-dbplay-maps  ’s_map-name) 


[LISP  Function] 
(LISP  Function] 
[LISP  Function] 
(LISP  Function] 


RETURNS:  Find- display- map  returns  the  display  map  which  has  an  ID  that  roost  pre¬ 
cisely  matches  the  ID  given  as  the  argument.  A  match  is  more  precise  if 
more  components  are  given:  e.g.,  ’(standard  matrix  polaroid-891  sun-475) 
matches  ’(standard)  but  matches  ’(standard  matrix  polaroid-891)  more  pre¬ 
cisely.  Find- display- map  returns  nil  if  there  b  no  matching  map. 


Find- display- maps  returns  a  list  of  all  the  dbplay  map>s  that  whose  ID 
matches  the  ID  given  as  the  argument. 
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(flush-display  [T^delay]  |’clis  '(hviiudisplay!  !/])  [LISP  Function] 

WHERE:  Dis/(hvin_(lisplny  dcrniills  lo  ilic  value  of  ((7cf-cwrrc7i^-rfj5p/ay-u;iWow^).  If 
dis/dwin_display  is  a  display  window,  it  is  replaced  by  its  parent  display. 

Nil  arguments  are  ignored  (so  any  argument  may  be  nil). 

SIDE  EFFECT:  If  dis_display  has  no  huf^-dtricc  or  has-parcnt,  this  function  does  nothing. 

If  dis_display  has  a  iHiS'dcvicc,  flush- display  delays  until  all  commands 
sent  to  the  display  have  actually  been  executed  by  the  display  hardware, 
and  then  returns  If  Ldelny  is  given,  a  timer  is  set  which  will  ensure  that 
the  display  hardware  will  not  accept  any  subsequent  display  command 
until  f_delay  seconds  after  the  last  of  these  commands  is  finished. 

If  dis_display  hn.s  a  hnS’parevf,  then  dis^display  is  merged  into  this  parent 
by  the  vierye-displaij  function,  and  then  flush-display  is  executed  on  the 
parent. 

A  record  is  kept  of  which  parts  of  the  display  have  been  changed  since  the 
Inst  flush,  so  as  to  avoid  redundant  work.  The  I  argument  causes  this 
liirsh  to  believe  the  entire  display  has  been  changed  since  the  last  flush.  It 
is  useful  if  the  screen  is  destroyed  accidentally  and  needs  to  be  refreshed. 

(make-display-map-array  ni_gamma.  (LISP  Function) 

’(n_red  n_green  n_blue  x_size  (n_first  (njast))) 

...) 

RETURNS:  An  array  suitable  for  use  as  a-display-map  has-map- array  \K\\ie  for  a  display 
that  takes  8-bit  red,  blue,  and  green  intensities  (in  that  order).  The  array  is 
made  by  filling  in  x_size  rows  from  each  list  argument  of  the  form 

(n_red  n_green  n_blue  JLjsize  (n_first  (njast))). 

The  first  three  elements  of  this  list  define  the  relative  sizes  of  the  red,  green, 
and  blue  components  of  some  color. 

The  assumption  is  that  the  intensities  on  the  screen  are  the  gamma  power  of 
the  numbers  in  the  pseudocolor  map,  and  the  total  intensity  of  a  color 
(R  G  B)  is 

R  **  gamma  -I-  G  **  gamma  -f  B  **  gamma. 

The  numbers  in  the  map  are  to  give  a  linear  scale  of  increasing  total  intensi¬ 
ties. 

N_first  **  gamma  is  the  desired  intensity  for  the  first  element  filled  in. 
Njast  **  gamma  is  the  desired  intensity  for  the  last  element  filled  in.  If 
njast  is  omitted  or  given  as  ni7, 

(red  **  gamma  -f  green  **  gamma  +  blue  gamma)  **  (l/gamma). 
is  used  as  njast.  If  n_first  is  omitted  or  given  as  m7, 
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((n^last  **  n_gamma)  /x_size)  **  (1/gamma) 
will  be  UbecI  n_firsi 

The  X  size  of  the  resulting  map  array  is  3.  The  Y  size  is  the  sum  of  all  the 
.\_size's. 

N_gamma  defaults  to  1.0.  Values  for  gamma  can  be  inserted  anywhere  in  the 
argument  list  and  will  affect  subsequent  arguments  only. 

(merge-display  ’dis^display  I’dwin^window]  (LISP  Function] 

|’dwpt_upper-left|  |/ios-rooms  '(n_xzoom  n^yzoom)] 

[liaS‘Siz€s  \n_xsize  n_ysize)] 

\hc^-oricn!aiioji  's^orientationj 
\has-plane-7nap  ’((bpn_source-l  bpn_target-l)  ...)] 

\hafi-color-viap  ’((s_source-l  s_target-l)  ...)j 
’((s_source-l  s_target-l)  ...)]) 

*display-plane-map*  [LISP  Global  Variable] 

*display-color-map*  |LISP  Global  Variable’ 

*display-map-map’*  [LISP  Global  Variable] 

WHERE:  The  dwin^window,  dwpt_upper-left.  n_xzoom,  n_yzoom,  n_xsize,  n^ysize  and 
s^orientation  arguments  are  passed  to  the  nexv-window  function  to  get  a  win¬ 
dow  referred  to  as  dwin^window  below. 

The  has-planc-map  argument  maps  bitgraph  plane  names  of  dis_display  onto 
bitgraph  planes  of  dwin_window.  The  entries  consist  of  a  dis_display  plane 
name  followed  by  a  dwin_window  plane  name.  In  addition,  an  entry  of  the 
form  — 

(s_source  s_target) 

implies  entries  of  the  form  — 

((s^source  x_N)  (s^target  x_N)) 

for  each  integer  x_N,  except  for  those  x_N  for  which  has- plane-map  already  has 
an  entry  with  bpn_source  equal  to  (s_source  x_N). 

The  has-color-inap  argument  maps  the  names  of  colors  associated  with 
dis^display  to  colors  associated  with  dwin.window.  It  is  only  used  when 
dis^display  has  a  bitgraph  array  or  bitgraph  programs,  while  dwin^window  has 
only  an  intensity  array,  and  neither  bitgraph  array  or  programs.  In  this  case 
the  bitgraph  information  of  dis_display  is  merged  directly  into  the  intensity 
array  of  dwin_window  and  a  mapping  of  colors  is  possible. 

The  has-map-map  argument  maps  display  has-map  names.  This  is  nessary  to 
pass  error  checks  if  dwin_window’s  parent  has  a  different  has-map  attribute 
than  dis_display,  and  both  have  intensity  arrays. 

The  has-plane-inap  argument  defaults  to  the  value  of  the  *  display- plant-map* 
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global  variable,  which  itself  defaults  to  nil.  The  lias-color-map  argument 
defaults  to  the  value  of  the  *  display- color-map*  global  variable,  which  itself 
defaults  to  nil.  The  has-map-map  argument  defaults  to  the  value  of  the 
*  display- map- map*  global  variable,  which  itself  defaults  to  nil. 

SIDE  EFFECT:  Copies  the  information  in  dis_display  into  dwin_window.  The  upper  left 
corner  of  dis_display  is  copied  to  the  upper  left  corner  of  dwin_window.  If 
dis^display  is  too  small,  the  right  or  bottom  of  dwin_window  is  left 
unchanged,  and  if  dis^display  is  too  large,  its  right  or  bottom  is  not 
copied.  The  intensity  array  of  dis_display  is  copied  into  the  intensity 
array  of  dwin^window,  if  both  intensity  arrays  exist.  The  pixels  of 
dis_display  are  expanded  by  the  zooms  of  dwin_window  when  copied. 

If  dis_display  has  bitgraph  programs,  and  d\vin_window  has  either  bit- 
graph  programs  or  a  bitgraph  array  or  both,  each  bitgraph  plane  M  of 
dis_display  is  logically  OR*ecl  into  the  bitgraph  plane  N  of  dwin_window 
with  the  same  bitgraph  plane  nam^. 

If  instead  dwin_window  only  has  an  intensity  array,  and  no  bitgraph  pro¬ 
grams  or  bitgraph  array,  the  bitgraph  planes  of  dis_display  overlay  the 
intensity  information  in  dwin_wiiKlow.  This  overlay  is  done  after  any 
intensity  information  in  dis_clisplay  is  copied  into  dwin_window.  Informa¬ 
tion  from  planes  with  higher  numbers  in  dis_display  overlays  information 
from  planes  with  lower  numbers.  The  bitgraph  array  of  dis_display  is 
used  if  it  exists  and  dwin_window  has  zooms  equal  to  1.  Otherwise 
dis_display’s  bitgraph  program  is  used,  and  the  dis_display  plane  types 
are  recompiled  for  dwin_window. 

If  dis_display  and  dwin_window  both  have  bitgraph  arrays  but  no  bit- 
graph  programs,  and  if  the  zooms  of  dwin_window  equal  1.0,  the  bitgraph 
planes  of  dis_display  will  be  logically  OR’ed  into  those  of  dwin_window  as 
indicated  above.  Similarly  if  instead  dwin_window  has  an  intensity  array 
but  no  bitgraph  programs  or  bitgraph  array. 

It  is  not  an  error  if  only  one  of  dis_display  and  dwin_window  have  inten¬ 
sity  arrays,  or  if  only  one  has  bitgraph  planes.  It  is  an  error  if  diaudisplay 
has  a  bitgraph  array  and  no  bitgraph  programs,  and  cither  dwin_window 
has  bitgraph  programs,  or  dwin_window  has  zooms  not  equal  to  1  or  an 
upper  left  corner  with  non-integer  coordinates. 
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(move-display-cursor-by  ’n_\displaceinenr  n_y displacement 

['dw  in^windowj) 

(move-display-cursor-by  ’(n.xdisplacement  n^ydisplacement) 

pdwin^window]) 

(move-display-cursor-by  ’vec*_vector  ['dwiii_windo\v]) 

(move-display-cursor-to  ’n_xposition  ’n_yposition 

pdwin_windo\v]) 

(move-display-cursor-to  ’(n_xposition  n_y position) 

pdwin_window]) 

(move-display-cursor-to  ’pt_point  pdwin_window]) 

W'HERE:  Dwin_windo\v  defaults  to  the  value  of  [get- curt cnt- display- window). 

SIDE  EFFECT:  Resets  the  coordinates  of  the  cursor  point  for  the  window.  Move-display- 
cur$or-by  adds  displacements  to  the  current  coordinates,  while  move- 
display-cursor-to  replaces  the  coordinates.  A  nil  displacement  or  position 
may  be  used  to  indicate  the  associated  cursor  coordinate  is  not  to  be 
modified. 


[LISP  Function] 

[LISP  Function] 

[LISP  Function] 
[LISP  Function] 

[LISP  Function] 

[LISP  Function] 


(new-plane  'bpn_plane)  [LISP  Function] 

EQU1^^\LE^T  TO:  {seif  {hasi-planc  [gei-ctirrenf-display-window))  bpn_plane). 

(new-window  [’d\vin_\vindo\v]  [’d\vpt_upper-left]  ...)  [LISP  Function] 

WHERE:  D\vin_window  defaults  to  the  value  of  [get-currevf-display-window)  and 
dwpt_upper„left  defaults  to  '(0.0  0.0).  The  dwin_window  and  dwpt_upper-left 
arguments  may  be  given  in  any  order,  and  may  be  mixed  with  nil  arguments 
which  are  ignored. 

EQUIVALENT  TO: 

{a- display- window  dwin_window 

has-parent  dwin^window 
has-upper-left  dwpt_upper-left 

•••) 

except  that  dwpt_upper-left  is  offset  by  the  dwin^window  has- cursor 
position. 

Note  that  because  dwiD_window  is  both  the  prototype  and  the  parent, 
the  new  window  will  inherit  has-transform  and  other  attributes  from 
it,  while  also  having  its  upper  left  corner,  sizes,  zooms,  and  orientation 
defined  in  terms  of  it. 
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(playback-display  ’dis.display  pd\vin_\vindow])  [LISP  Function] 

(playback-display  i’dwin.Nvindow])  [LISP  Function) 

(playback-display  'ca.catalog  [‘dwin^windowj)  [LISP  Function] 

(playback-display  ’s_file-name  [’d\vin_windowj)  [LISP  Function] 

WHERE:  D\vin_window  defaults  to  the  value  of  {gcl-play back- display- window). 

SIDE  EFFECT:  This  function  is  used  to  play  back  displays  stored  in  a  catalog. 


If  dis_display  is  given  the  function  is  equivalent  to— 

{merge- display  dis_display  dwin_window) 
{flush- display  dwin^window) 


If  fto  argument  is  given  the  function  is  equivalent  to— 

{flush- display  dwin_window  t) 


If  ca_catalog  is  given  the  function  positions  to  the  beginning  of  the  catalog 
and  enters  interactive  mode  wherein  it  types  the  prompt  ‘playback >  ’ 
and  reads  commands.  A  carriage  return  reads  the  next  catalog  entry  and 
displays  it  if  it  is  a  display,  or  pretty-prints  it  otherwise.  A  lisp  expression 
followed  by  a  carriage  return  reads  the  catalog  entry  whose  location 
equals  the  lisp  expression  and  displays  or  pretty-prints  it.  However,  in 
this  case  if  the  entry  read  has  the  form— 

{catalog-key  location-used- to-read-en try), 

it  is  replaced  by  the  catalog  entry  following  it  before  being  displayed  or 
pretty-printed.  A  character  lists  all  the  allowable  locations  if 
ca_catalog  is  an  index  catalog.  A  character  lists  help  information. 
And  a  control-D  or  the  character  causes  the  function  to  exit. 

Giving  s_file-name  is  just  like  giving  the  catalog— 

{a-catalog  is-index-of  {a-catalog  has-file  ’s_file-name)). 

(remake-display-maps  ’(s_map-name  [s_monitor  ...])  [LISP  Function] 

*at_attribute  ’g_value  ...) 

(remake-display-maps  ’s_maj>-name  (LISP  Function] 

’at_attribute  ’g_value  ...) 

EQUIVALENT  TO: 

{dolist{d  {find- display-maps  ’(s_map-name  (s^monitorj  ...))) 

{a- display-map  d  at_attribute  g^value  ...)) 

This  is  useful  for  resetting  attributes  like  has- plane- types  and  has- 
scales  for  all  display  maps  matching  a  given  ID. 
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(write-display  ’ca_cataIog]  l’dis/ci\vin«display])  [LISP  Function] 

WHERE:  Dis/d\vin_display  defaults  to  the  value  of  {get-currcnf-display-wiiidow).  If 
dis/dwin_display  is  a  display  window,  it  is  replaced  by  its  parent  display. 

Nil  arguments  are  ignored  (so  any  argument  may  be  niY). 

SIDE  EFFECT:  If  dis_display  has  no  has-parent,  this  function  docs  the  same  thing  as— 

{write-catalog  ca_cataIog  dis_display). 

If  dis_display  has  a  has-parcnt,  then  dis_display  is  merged  into  this  parent 
by  the  mtrgc-display  function,  and  then  wriit-display  is  executed  on  the 
parent. 

A  display  that  has  been  written  into  a  catalog  can  be  read  back  from  the 
catalog  and  redisplayed  with  the  merge-display  function. 
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!•  GLOSSARY. 

(auto-clip  ’lar_array  ’x_area  ’n_range  [LISP  Function] 

(’(n_n^imum  n^maximum)  [’n_extension]]) 

RETURNS:  Clipping  bounds  for  lar_array  in  the  form  of  a  range  specified  by  a  list  with 
two  elements: 

(njower- bound  n_upper- bound). 

X_area  represents  a  number  of  points  in  lar_array,  hence  an  area  if  lar.array 
is  two  dimensional,  a  volume  if  three  dimensional,  etc.  Lar.array  is  histo- 
grammed  with  a  resolution  of  n_range/lO.  Then  a  tight  range  is  chosen  as 
small  as  possible  so  that  no  histogram  interval  of  size  n_range  (10  histogram 
points)  wholy  outside  the  tight  range  has  as  many  as  x_area  points.  This 
implies  that  if  lar_array  is  thought  of  as  an  image,  any  object  with  values 
that  are  all  within  n_range  of  each  other  and  whose  values  are  also  wholy 
outside  the  tight  range  must  be  smaller  than  x^area  points. 

During  the  computation  of  the  histogram  points  with  missing  values  and 
points  with  values  outside  the  range  (n.minimum  n_maximum)  are  ignored. 
Thus  the  tight  range  will  be  inside  the  range  (n^inimum  o^aximum). 

Then  a  loose  range  is  computed  so  that  the  difference  between  each  loose 
bound  and  its  associated  tight  bound  is  =  n.extension  times  the  size  of  the 
loose  range.  The  default  value  of  n^extension  is  0.10. 

Lastly  the  intersection  of  the  loose  range  and  the  range  (n^inimum 
n_maximum)  is  returned. 
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(histogram  Mar_output  ’ar_input.-l  VuLruler-1  ...  (LISP  Function] 

'ar_input-N  'ruLruler-N) 

WHERE:  Where,  if  there  are  N  ar_input/ruLruler  pairs,  lar_output  is  treated  as  N 
dimensional.  N  must  be  from  1  through  4.  Ar_input-1,  ar_inpul-2,  ..., 
ar_input-N  must  all  be  similar.  The  exponent  of  lar_output  must  be  0  or  nega¬ 
tive. 

RETURNS:  Lar_output  after  modifying  its  elements. 

SIDE  EFFECT:  Adds  the  N  dimensional  histogram  of  ar_input-l,  ar_input-.N  to 
lar.output. 

Each  non-missing  valued  element  from  an  input  array  is  assigned  a  sub¬ 
script  obtained  by  applying  the  inverse  of  the  affine  transformation 
defined  by  the  ruler  associated  with  the  input  array,  and  rounding  the 
result  to  the  nearest  integer. 

Each  corresponding  set  of  elements  in  the  input  arrays  is  mapped  onto  N 
subscripts,  and  these  select  an  element  of  lar^output.  Ar_input-1  provides 
the  X‘dwicnsw7J  subscripts;  ar_input-2  the  Y-dirnenswn  subscripts: 
ar_inpiit-3  the  Z’dimttxsion  subscripts;  and  ar_input-4  the  T-diintvsion 
subscripts.  The  selected  element  of  lar_output  is  incremented  by  1.  If 
any  element  in  a  corresponding  set  of  input  elements  is  missing,  or  any 
subscript  defined  by  these  elements  is  out  of  range,  the  corresponding  set 
is  ignored. 

NOTE:  The  elements  in  lar_output  are  not  initialized  to  zero. 

BUG:  Lar_output  elements  may  not  have  missing  values. 

(histogram-of ’ar^input-l  VuLruler-1  ...  (LISP  Function) 

’ar_jnput-N  VuLruler-N) 

WHERE:  N  must  be  from  1  through  4.  Ar_input-1,  ar_input-2,  ...,  ar_input-N  must  all 
be  similar. 

If  the  range  specification  (second  element)  of  ruLruler-M  is  mV,  the  pair  com¬ 
puted  by 

{bounds- of- array  ar_array-M) 
will  be  substituted  for  it. 

For  example,  the  ruler  (nil  nil  2)  will  produce  a  histogram  with  bins  of  size  2 
(the  scale),  with  a  lower  bound  on  the  first  bin  (first  range  bound)  slightly 
smaller  than  the  lower  bound  of  all  the  elements  in  the  associated  array,  and 
with  as  many  bins  as  needed  to  ensure  that  all  array  elements  are  assigned  to 
some  bin. 

As  another  example,  the  ruler  (128  nil  (2))  will  produce  a  histogram  with  128 
bins  (histogram  dimension  size),  a  lower  bound  for  the  first  bin  (first  range 
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RETURNS; 


bound)  equal  to  the  lower  bound  of  all  the  elements  of  the  associated  array,  and 
a  bin  size  (scale)  which  is  the  smallest  multiple  of  2  that  will  fit  all  the  array 
elements  into  (he  128  bins. 

A  new  N  dimensional  array  lar_output  with  exponent  0  whose  elements  are 
computed  by  passing  it  and  the  other  parameters  to  the  histogram  function. 
Before  being  passed  the  rulers  have  intcgcrizc-rulcr  applied  to  them,  and  the 
resulting  domain  size  is  used  to  determine  the  corresponding  dimension  size  of 
lar_output. 

The  has-ruler  attributes  for  the  lar_output  dimensions  are  set  to  the  rulers 
used. 
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1.  MAKING  LINKED  EDGE  CHAINS 

With  the  functions  defined  in  this  package,  it  is  possible  to  detect  and  extract  edges 
in  a  2-D  array,  where  the  edges  are  defined  as  the  zero-crossings  of  the  convolution  with  a 
laplacian*of-gaussi||m  operator  or  with  some  other  contrast  operator. 

First,  the  input  array  must  be  convolved  with  the  appropriate  kernel;  for  example,  if 
al  is  the  input  array,  its  contrast  array  dgal  is  obtained  by 

(setq  dgal  (convolution-of  al  (del2g-kernel  ’(2.0  2.0)))) 

where  the  widths  of  the  Gaussian  kernel,  here  (2.0  2.0),  must  be  adapted  to  the  desired 
scale  of  details.  Second,  the  zero  crossings  of  the  contrast  array  and  the  slopes  at  these 
zero- crossings  are  estimated  and  stored  in  the  arrays  eal,  sal,  respectively  by 

(desetcj  (sal  eal)  (zero-edges-of  dgal  ’(2  2))) 

\i  this  point,  a  list  Ic  of  chains  of  linked  edge  points  can  be  obtained  as  the  value 
returned  by 

(setq  Ic  (linked-edges-of  eal  sal)) 

Each  chain  in  Ic  has  the  attributes  has-point~list  set  to  the  list  of  points  in  the  edge  and 
has-strength  to  the  average  strength  over  the  edge,  as  defined  in  the  strength  array  sal. 

In  addition  to  the  above  procedure,  it  is  also  possible  to  generate  edge  chains  with 
information  related  to  the  ranges  on  each  side  on  the  edge.  For  this  purpose,  the  initial 
array  al  must  first  be  convolved  with  a  smoothing  operator  corresponding  to  the  contrast 
operator  used  to  generate  dgal.  For  example,  the  smoothed  array  gal  is  obtained  with 

(setq  gal  (convolution-of  al  (gaussian-kernel  ’(2.0  2.0)  *(0.0  0.0)))) 

The  list  of  extended  edge  chains  xlc  is  then  obtained  with 

(setq  xlc  (x-linked-edges-of  cal  sal  gal)). 

In  addition  to  has-point-list  and  has-strength^  the  chains  in  xlc  have  their  has-minimum- 
ranges  attribute  set  to  the  list  of  ranges  on  the  lower  side  of  the  edge,  corresponding  to 
each  point  in  has-point-list]  the  has-min-median  is  set  to  the  median  of  the  values  in  the 
above  list.  Finally,  the  has-maximum-ranges  and  has-max~median  attributes  are  set  to 
corresponding  values. 

2.  ARRAY  SIZES,  OFFSETS,  ETC. 

The  sizes  of  the  various  arrays  described  above  are  briefly  discussed  in  this  section. 
Let  the  sizes  of  the  input  array  al  be  (N  M),  and  the  kernel  sizes  be  (K  K).  Note  first 
that  (K  K)  is  not  equal  to  (2  2)  in  the  above  example,  as  (2  2)  determines  the  side  of  the 
main  lobe  of  the  laplacian-of-gaussian,  not  the  size  of  the  kernel  array;  with  the  default 
^kernel-cutoff*,  K=12  in  this  example.  The  array  dgal  obtained  with  the  function 
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c onvolutiov- of  h?iS  sizes  (N+1  M-hl);  the  result  array  sizes  are  larger  than  the  input,  by 
one  element  whenever  the  kernel  sizes  are  even.  Furthermore,  individual  elements  of 
dgal  must  be  considered  as  offset  by  (0.5  0.5)  from  the  elements  of  al.  In  order  to  obtain 
dgal,  the  function  convolufiov-oj iniennWy  expanded  the  array  al  to  sizes  (N-hK  M+K). 

The  arrays  sal  and  eal  have  sizes  (N  M)  and  (N  M  2)  respectively.  The  function 
zcro-edgc$-of  always  expects  its  input  array  to  be  offset  by  half-pixels  in  each  dimension, 
and  outputs  arrays  with  sizes  one  less  than  the  input  sizes,  and  with  no  offsets.  In  order 
to  obtain  the  final  results,  the  input  array  to  zcro-cdgc$-of  dgal,  which  has  sizes  (N-hl 
M+l),  is  internally  expanded  to  sizes  (N+2W-1  M-h2W-l),  where  W  denotes  the  value  of 
each  width  argument  to  the  function  zero-edges-of  Reasonable  values  for  the  width  argu¬ 
ments  are  integers  close  to  the  widths  of  the  kernel  used  to  generate  dgal. 

In  the  case  the  extended  edge  chains,  the  minimum  and  maximum  ranges  are 
estimated  as  the  minimum  and  maximum  on  a  5x5  box  in  gal  around  each  edge  point. 
The  array  gal  must  not  be  offset  by  half-pixels,  so  that  the  convolution  kernel  used  for 
gal  is  obtained  by  explicitly  forcing  the  optional  offsets  to  (0  0).  Although  the  initial 
array  al  itself  could  be  supplied  as  the  third  argument  to  the  2-/i7i/:e</-erfycs-o/ function, 
using  the  smoothed  array  gal  is  more  compatible  with  the  detection  of  edges  as  zero 
crossings  of  dgal  which  is  equivalent  to  the  laplacian  of  gal. 


3.  GLOSSARY. 

(zero-edges  ar_edges  *lar_input  [’x_resolution))  [LISP  Function) 

WHERE:  The  element  type  of  ar_edges  is  a-cliar. 

There  are  integers  x_xwidth  >  1  and  x_ywidth  >1  such  that  the  X  and  Y 
dimension  sizes  of  ar_edges  are  2*x_xwidth-l  and  2*x_ywidth-l  less  than  the 
corresponding  sizes  of  larjnput.  The  Z  dimension  size  of  ar_edge  is  exactly  2. 

X_resolution  defaults  to  the  value  of  the  *dcfauU~cdgc~resolution*  variable, 
which  itself  defaults  to  8. 

RETURNS:  Ar_edges  after  its  elements  are  set. 

SIDE  EFFECT:  Zero  crossing  edges  are  found  in  lar^input  and  stored  in  ar.cdgcs. 

Arjnput  should  be  the  convolution  of  an  image  with  a  difference  of  gaus- 
sians  or  other  contrast  operator.  Its  zero  contours  are  the  edges  to  be 
found. 

Each  2X2  box  in  larjnput  is  checked  to  see  if  it  contains  an  edge  (0  con¬ 
tour).  If  it  contains  1,  that  is  output  into  ar.edges  according  to  the 
scheme  below.  If  it  contains  0  or  more  than  1,  ar.edges  is  marked  to  indi¬ 
cate  the  absence  of  an  edge  for  the  box.  The  rational  for  the  more  than  1 
case  is  that  the  edges  involved  would  have  nearly  zero  strength  (gradient 
in  larjnput  at  the  edge  location)  and  should  not  therefore  be  treated  as 
edges. 

The  2X2  larjnput  boxes  are  mapped  onto  RxR  point  boxes  where  R  is 
the  resolution.  If  R  were  8,  the  box  would  have  32  boundary  points 
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numbered  as  follows: 


0  1  2 

31 
30 
29 
28 
27 
26 
25 

24  23  22 


3  4  5  6  7  8 

9 

10 
11 
12 

13 

14 

15 

21  20  19  18  17  16 


The  ar_edges  elements  with  coordinates  (X  Y  0)  and  (X  Y  1)  receive  a  pair 
of  box  boundary  numbers  from  the  2X2  ar_input  box  whose  upper  left 
corner  subscripts  are 

(X-Hx_xwidth-1  Y-f-x_ywidth-l). 

This  pair  of  points  define  a  straight  line  which  is  the  edge  within  the  box. 
The  pair  is  chosen  so  that  going  from  the  (X  Y  0)  boundary  point  to  the 
(X  Y  1)  boundary  point  places  the  more  intense  part  of  the  image  on  the 
righthand  side. 

If  there  is  no  edge  in  the  ar_input  box,  a  pair  of  SAT_CMISSING  values  is 
output  to  the  two  ar_edges  elements. 

To  avoid  redundancy  edges  equal  to  the  right  or  bottom  edge  of  the  box 
are  surpressed  (they  will  be  the  left  or  top  edge  of  an  adjacent  box.  Edges 
are  also  surpressed  if  their  two  boundary  points  are  equal  (i.e.  0  length 
edges,  which  would  only  occur  at  the  box  corners). 

(lero-edges-of ’ar_input  ’(x_xwidth  x_ywidth)  [LISP  Function) 

[’x_resoIution]) 

WHERE:  X_xwidth  and  x_ywidth  should  be  the  widths  of  the  difference  of  gaossians  or 
similar  kernel  convolved  with  the  original  image  to  produce  ar_input. 

RETURNS:  A  list  (Iar_output  Iar_edges)  of  two  arrays  as  produced  by  zero-edge-strength 
and  zero-edges.  Prepare-array  is  applied  to  ar_input. 

WARNING:  The  two  arrays  returned  will  not  be  protected  against  garbage  collection 
unless  they  are  immediately  stored  in  variables  by  desetq  or  the  equivalent. 
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(rero-edge-strength-of  Mar_output  ’lar_input.  [LISP  Function) 

’Iar_work  ’ar_edges) 

WHERE:  The  X  and  Y  dimension  sizes  of  lar_output,  lar_work,  and  lar_input  are  the 
same,  and  there  are  integers  x_xwidth  >  1  and  x_ywidth  >  1  such  that  these 
sizes  are  larger  than  the  X  and  Y  sizes  of  ar_edges  by  2*x_xwidth-l  and 
2*x_ywidth*l.  Ar_edges  has  been  computed  from  ar_input  by  using  the  zero- 
edges  function.  Bfa_work  is  a  temporary  work  area. 

X_xwidth  and  x_ywidth  should  be  the  widths  of  the  difference  of  gaussians  or 
similar  kernel  convolved  with  the  original  image  to  produce  ar_input. 

RETURNS:  A  slice  of  lar_output  which  has  the  same  X  and  Y  dimension  sizes  as 
ar_edges. 

SIDE  EFFECT:  For  each  element  with  subscripts  (X  Y)  in  lar_output,  the  maximum  and 
minimum  are  found  of  the  2*>L-Xwidth  X  2*x_ywidth  box  in  ar^input  with 
upper  left  corner  subscripts  (X  Y).  The  difference,  the  maximum  minus 
the  minimum,  is  output  to  the  lar.output  clement  if  the  corresponding 
element  of  ar^edge  has  an  edge.  This  is  a  measure  of  the  strength  of  that 
edge.  If  there  is  no  edge,  0  is  stored  in  the  lar_output  element.  The 
corresponding  ar.edge  elements  have  subscripts  (X  Y  ...). 

The  theory  is  that  the  strength  is  roughly  the  size  of  the  gradient  across 
the  edge,  and  this  can  be  measured  roughly  by  the  maximum  minus  the 
minimum  on  a  box. 
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1.  GLOSSARY. 

(box-linear- fit  ’lar_output  ’lar_input  [LISP  Function] 

x_ysize)  ’(x_xstep  x_ystep)) 

WHERE: 

lar_output  X  dimension  size  = 

(lar_input  X  dimension  size  -  x_xsize  -I-  x_xstep)  /  x_xstep 

and  similarly  for  the  Y  dimension.  The  Z  dimension  size  of  lar_output  must  be 
4. 

The  exponents  of  lar_oiitput  and  lar_input  must  be  identical. 

RETITINS:  Lar_output  after  setting  its  elements. 

SIDE  EFFECT.:  For  each  (X  Y)  coordinates  in  lar_output,  a  linear  fit  is  done  of  all  the 


points  in  the  (x_xsize  x_ysize)  box  with  upper  lefthand  corner  (X*x_xstep 
Y*x_ystep)  in  lar_input.  The  following  linear  fit  parameters  are  recorded 
in  the  elements  (X  Y  Z)  of  lar_output; 

Z  =0 

Constant. 

Z  =  1 

X  Derivative. 

Z  =2 

Y  Derivative. 

Z  =3 

Standard  Deviation. 

The  equation  of  fit  is 

value  at  (Xl  Yl)  =  Constant  -I- 

(X  Derivative)  *  (Xl  -  X  *  x_xstep  -  (x_xsize  -  1)  /  2) 

(Y  Derivative)  *  (Yl  -  Y  *  x_ystep  -  (x_ysize  -  1)  /  2) 

where 

(X*x_xstep-f(x_xsize-l)/2  Y*x_ystep+(x_ysize-l)/2) 
is  the  center  of  the  box. 

The  constant,  derivatives,  and  standard  deviation  are  recorded  as  missing 
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if  there  are  fewer  than  3  non-missing  values  in  the  box,  or  if  the  non¬ 
missing  points  lie  in  a  straight  line.  If  there  are  4  non-missing  values  not 
on  a  straight  line,  just  the  standard  deviation  is  recorded  as  missing. 

(box-linear-fit-of  ’arjnput  ’(x_xsize  x_ysize)  [LISP  Function] 

’(x_xst.ep  x_ystep)) 

RETURNS:  An  array  lar_output  whose  elements  are  set  by  calling  box-lincar-fii  with 
lar_output,  ar_input,  (x_xsize  x_ysize),  and  (x_xstep  x_ystep)  as  arguments. 
Prepare-array  is  run  on  ar_input  to  change  its  numeric  type  and  expand  it  by 
(x_xsize-l  x_ysize-l)  if  appropriate. 
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CHAPTER  15 


TEXTURE 


1.  GLOSSARY. 

(box-horizontal-total-variation  ’lar_output  ’lar_input  [LISP  Function] 

’(x_xsize  x_ysize)  ’(x_xstep  x_ystep)) 

WHERE: 

lar_output  X  dimension  size  = 

(lar_input  X  dimension  size  -  x_xsize  +  x_xstep)  /  x^xstep 

and  similarly  for  the  Y  dimension. 

The  exponents  of  lar_output  and  lar_input  must  be  identical. 

x_xsize  and  x_ysize  must  be  greater  than  1. 

RETURNS:  Lar_output  after  setting  its  elements. 

SIDE  EFFECT.:  For  each  (X  Y)  coordinates  in  lar_output,  the  normalized  horizontal  total 
variation  is  computed  for  all  the  points  in  the  (x_xsize  x_ysize)  box  with 
upper  lefthand  corner  (X^x^step  Y*x^step)  in  lar_input.  The  com¬ 
puted  quantity  is  the  sum  of  absolute  values  of  differences  between  pairs 
of  horizontal  neighbors  in  the  box,  divided  by  the  total  number  of 
differences  involved. 

BUG:  Cannot  handle  missing  values. 

(box-horizontal-total-variatioD-of  *ar_input  ’{x^xsize  x_ysize)  [LISP  Function] 

*(x_xstep  x_ystep)) 

WHERE:  x^xsize  and  x_ysize  must  be  greater  than  1. 

RETURNS:  An  array  •iar.output  whose  elements  are  set  by  calling  box- horizontal- total- 
vartafion  with  lar^output,  ar^input,  (x^jcsize  x_ysize),  and  (x_xstep  xjrstep) 
as  arguments.  Prepare-array  is  run  on  arjinput  to  change  its  numeric  type 
and  expand  it  by  (x_xsize-l  x_ysizc-l)  if  appropriate. 
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(box-minimum-total-variation  ’Iar_output  ’Iar_input 

’(x_xsize  N_ysize)  ’(x_xstep  x_ystep)) 


[LISP  Function) 


WHERE: 

lar_output  X  dimension  size  = 

(larjnput  X  dimension  size  -  x_xsize  -f  x_xstep)  /  x_xstep 


and  similarly  for  the  Y  dimension. 


The  exix)nents  of  Iar_output  and  larjnput  must  be  identical. 

x_xsize  and  x_ysize  must  be  greater  than  1. 

RETURNS:  Lar_o<|^ut  after  setting  its  elements. 

SIDE  EFFECT  :  For  each  (X  Y)  coordinates  in  Iar_output,  the  normalized  minimum  total 
variation  is  computed  for  all  the  points  in  the  (x_xsize  x_ysize)  box  with 
upper  lefthand  corner  (X*x_xstep  Y*x_ystep)  in  larjnput.  The  com¬ 
puted  quantity  is  the  minimum  of  the  normalized  horizontal  total  varia¬ 
tion  and  vertical  total  variation  in  the  box,  where  the  normalized  hor¬ 
izontal  total  variation  is  the  sum  of  absolute  values  of  differences  between 
pairs  of  horizontal  neighbors  in  the  box,  divided  by  the  total  number  of 
differences  involved,  and  the  other  variation  is  similarly  defined  for  verti¬ 
cal  neighbors. 

BUG:  Cannot  handle  missing  values. 


(box-minimum-total- variation-of  ’arjnput  ’(x_xsize  x_ysize)  [LISP  Function) 

’(x_xstep  x_ystep)) 

WHERE:  x_xsize  and  x_ysize  must  be  greater  than  1. 

RETURNS:  An  array  lar_output  whose  elements  are  set  by  calling  box-mimmum-total- 
vartation  with  lar_output,  arjnput,  (x_xsize  x_ysize),  and  (x_xstep  x_ystep) 
as  arguments.  Prepare-array  is  run  on  arjnput  to  change  its  numeric  type 
and  expand  it  by  (x_xsize-l  x_ysize-l)  if  appropriate. 


(box-standard-deviation  ’lar_output  ’larjnput 

’(x_xsize  x_ysize)  ’(x_xstep  x_ystep)) 


[LISP  Function) 


WHERE: 

lar_output  X  dimension  size  = 

(larjnput  X  dimension  size  -  x_xsize  -I-  x_xstep)  /  x_xstep 


and  similarly  for  the  Y  dimension.  The  Z  dimension  size  of  lar_output  must  be 

2. 


The  exponents  of  lar_output  and  larjnput  must  be  identical. 

RETURNS:  Lar_output  after  setting  its  elements. 

SIDE  EFFECT  :  For  each  (X  Y)  coordinates  in  Iar_output,  the  mean  and  standard  devia¬ 
tion  are  computed  for  all  the  points  in  the  (x_xsize  x_ysize)  box  with 
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upper  lefthand  corner  (X*x_xstep  Y*x_ystep)  in  lar_input.  These  param¬ 
eters  are  recorded  in  the  elements  (X  Y  Z)  of  lar_output: 

Z  =  0  Mean. 

Z  =  1  Standard  Deviation. 


The  mean  and  standard  deviation  are  recorded  as  missing  if  there  are  no 
non-missing  values  in  the  box.  If  there  is  only  1  non-missing  value,  just 
the  standard  deviation  is  recorded  as  missing. 


(box-Bt&ndaTd-d^ia.tion-of  ’ar_input  ’(x_xsize  x_ysize)  (LISP  Function] 

’(x_xstep  x_ystep)) 

RETliRNS:  An  array  lar_output  whose  elements  are  set  by  calling  box-standard-devialion 
with  lar_output,  ar_input,  (x_xsize  x_ysize),  and  (x_xstep  x_ystep)  as  argu¬ 
ments.  Prepare-array  is  run  on  ar_input  to  change  its  numeric  type  and 
expand  it  by  (x_xsize-l  x_ysize-l)  if  appropriate. 


(box-vertical-total- variation  ’lar_output  ’lar_input  [LISP  Function] 

’(x_xsize  x_ysize)  ’(x_xstep  x_ystep)) 


WHERE: 


lar_output  X  dimension  size  = 

(lar_input  X  dimension  size  -  x_xsize  -1-  x_xstep)  /  x_xstep 

and  similarly  for  the  Y  dimension. 

The  exponents  of  lar.output  and  Iar_input  must  be  identical. 


x_xsize  and  x_ysize  must  be  greater  than  1. 

RETURNS:  Lar_output  after  setting  its  elements. 

SIDE  EFFECT.:  For  each  (X  Y)  coordinates  in  lar_output,  the  normalized  vertical  total 
variation  is  computed  for  all  the  points  in  the  (x_xsize  x_y8ize)  box  with 
upper  lefthand  corner  (X*x_xstep  Y*x_y8tep)  in  lar_input.  The  com¬ 
puted  quantity  is  the  sum  of  absolute  values  of  differences  between  pairs 
of  vertical  neighbors  in  the  box,  divided  by  the  total  number  of  differences 
involved. 

BUG:  Cannot  handle  missing  values. 


Printed  April  28,  1989 


TEXTURE 


lS-4 


(box- vertical- total-variation-of  ’ar_input.  ’(x_xsize  x_ysize)  (LISP  Function] 

’(x_xstep  x_ystep)) 

WHERE;  x_xsize  and  x_ysize  must  be  greater  than  1. 

RETURNS:  An  array  lar_output  whose  elements  are  set  by  calling  box-vertical-total- 
variation  with  lar_output,  ar_input,  (x_xsize  x_j8ize),  and  (x_XBtep  x_ystep) 
as  arguments.  Prepare-array  is  run  on  ar_input  to  change  its  numeric  type 
and  expand  it  by  (x_xsize-l  x_ysize-l)  if  appropriate. 
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+ . (LISP  Global  Variable] 

-h-b .  . [LISP  Global  Variable] 

. (LISP  Global  Variable] 

. (LISP  Global  Variable] 

** .  . . . (LISP  Global  Variable] 

. . [LISP  Global  Variable] 

•^Od.vector*"  . . (LISP  Global  Variable] 

*ld-to2d-zero-transform* . [LISP  Global  Variable] 

*ld-to-3d-zero- transform* . [LISP  Global  Variable] 

*ld-unit-transform* . [LISP  Global  \^ariable] 

*ld-x-unit-vector* . [LISP  Global  Variable] 

*ld-*ero-transform* . . . [LISP  Global  Variable] 

*  Id-zero-vector  ^  . .  . [LISP  Global  Variablej 

*2d-to-ld-zero-transform* . [LISP  Global  Variable' 

*2d-to-3d-zero-transform* .  . [LISP  Global  Variable^ 

*2d-unit-transform* . . . . . [LISP  Global  Variable 

*2d-x-unit-vector * .  ....  ..  .  . [LISP  Global  Variable 

*2d-y-unit-vector* .  . [LISP  Global  Variable 

*2d-*ero-transform* .  . .  .  . [LISP  Global  Variable] 

*2d-*ero-vector*  . [LISP  Global  Variablej 

*3d-to-ld-rero-transform* . [LISP  Global  Variable] 

*3d-to-2d-zero-transform* . (LISP  Global  Variablej 

*3d-unit-transform* . [LISP  Global  Variable] 

*3d-x-unit-vector* . [LISP  Global  Variable] 

*3d-y-unit-vector* . [LISP  Global  Variablej 

* 3 d-£cro- transform* . [LISP  Global  Variable] 

*3d-zcro- vector* . [LISP  Global  Variable] 

*3d-£-unit-vcctor* . [LISP  Global  Variable] 

a-bignum . [SKETCH  Type] 

a-binary-function . (SKETCH  Type] 

a-bitgraph- character . [SKETCH  Type  Object] 

(a-bitgraph-parametcr-set  has-lint-width  ’x^line-width . [LISP  Macro] 

has-I-width  ’x_l-width  has-l-htighl  ’x_l-height 
has'5-widih  ’x«S-width  has-5-hcight  ’x_S-hcight 
fias-lO-width  *x_10-width  ha$-10-hcight  *x_10-height) 

**abnormal  object” . : . [SKETCH  Term] 

(abnormal-object-for-macro  ’(/wi  s_type  s_attribute  g_value  ...)) . [LISP  Function] 

(absolutc-value-array-clemcnts  ’lar_output  [*lar_input]) . [LISP  Function] 

(a-catalog  [ha$-fiU  *s_file-name] . [SKETCH  Object] 

[has‘fillcr  '(u^function  ,ca_input-catalog)] 

[ts-index-of  ca_indexed-file] 

[has-\ndtz-fUt  ’s_index-file] 

[has-indcx-function  ’u_index-function]) 


3-28 
3-28 
3-28 
3-28 
3-28 
3-28 
10-2 
10-1 
10-1 
10-1 
10-2 
10-1 
10-2 
10-1 
10- 1 
lO-l 
10-2 
10-2 
10-1 
10-2 
10-1 
10-1 
10-1 
10-2 
10-2 
10-1 
10-2 
10-2 
5-29 
5-29 
9-14 
9-1 


5-30 

5-31 

8-1 

e-4 


SKETCH  INDEX 
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(accumulate-filter  ’lar^array  ’.\_dimension) .  . [LISP  Function] 

a-char . [SKETCH  Type) 

(a-character-set  has- file  . [SKETCH  Type  Macro] 

has -font  ’s_font 

has- sizes  '(x_xsize  ’x.ysize)) 

a-character-set . [SKETCH  Type  Object] 

(a-cluster  \has-poinl-array  ’ar_point-array] . [LISP  Macro] 

\has-potnt-ltst  ’(pt^point-l  ...)] 

’g_ch  a  in-switch] 

\is-7naxiwal-polygon  ’g_maxiniaI-polygon-switch]) 

a-cluster  . [SKETCH  Type  Object] 

(add-arrays  ’lar_output  Mar_input-1  [Mar_input-2]) . [LISP  Function] 

(add-to-array-elements  ’lar_array  ’n.addend) . [LISP  Function] 

adim_ . [Argument  Prefix] 

(a-display  [lias-sizes  ’(x_xsize  x_ysize)j . [SKETCH  Type  Macro] 

■5_niap-name] 

[has-devtce  *(s_device-lype  ...)] 

[has- film  ■s_film! 

[has-parent  ‘dwin.windowj 
\has-bitgraph-planes  ’(s_plane-type-name-l  ...)] 


[h as-i nt ensity-array  ’ucar/usar/s_in tensity-array] 

\has-bitgraph-array  'ubar 's_bitgraph-array] 

\has-bitgraph-pragrams  ’h  's_bitgraph-programs]) 

a-display . [SIvETCH  Type  Object] 

(a- display-map  has-ids . [SKETCH  Type  Macro] 

’((s_map-name  [s_monitor  [s_film]  [s_processor]])  ...) 
[has-prtmary-colors  ’(s_primary-color-l  ...)] 
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(compose-display-orientations  's_second) . [LISP  Function] 

(compose-transforms  ’irans^transfornvl  transit ran$forni-2) . [LISP  Macro] 

*  computer-format'*' . [LISP  Global  Constant] 

${COMPUTER^TYPE) . (MAKE  Macro] 

S(COMPUTER^TYPE) . [UNIX  Environment  Variable) 

(contrast-of  ’ar_input  '(x_width  ...) . [LISP  Function) 

[’n_background  [’n_center]]) 

(convolution-of  *ar_input  ’ar_kernel) . [LISP  Function] 

(convolve  ’lar_output  'lar_input  ’ar_kernel) . (LISP  Function] 

(copy-array  *ar_output  ’ar_input) . [LISP  Function) 

(copy-catalog  ’g_input  ’g_output  (’(g^key  ...)]) . (LISP  Function] 

(copy-list  ’Llist  [’xjength  'g_fill]) . (LISP  Function] 

(copy-of-array  ’ar_input) . (LISP  Function) 

(copy-setf-function  ’s_symbol  ’s^source) . (LISP  Function] 

(copy-string  ’t_string) . [LISP  Function] 

(cos- array-elements  'lar_output  (1ar_inpur) . [LISP  Function] 

$(COUNT) . ! . [MAlvE  Macro] 

count . (MAJvE  Target] 

COUNT . (MAKE  Target] 

COUNT . [UNIX  File  Name] 

$(COUNT_FLAGS) . [MAlvE  Macro] 

$(CPP) . . . . . [MAlvE  Macro] 

$(CPP_FLAGS) . . . [MAJvE  Macro] 

${CPP_PATH) . . (MAKE  Macro] 

$(CPP_PATH) . (UNIX  Environment  Variable] 

“create'' . . [SKETCH  Term] 

(create-object  ’(ty_type  at_attribute  g^value  ...) . [SlvETCH  Operation  Macro] 

(*ob_prototype]) 

create-objcct . (SKETCH  Operation] 

(create-parent-object  ’opd_descriptor . . . (LISP  Macro] 

’(ty.type  at.attribute  g_value  ...)  (’ob_prototype]) 

.cs . [UNIX  File  Ebctension] 

cset_ . [Argument  Prefix) 

$(CSFILES) . [MAKE  Macro] 

csh.rc . [UNIX  File] 

'^current-display-window'^ . [LISP  Global  Variable] 

dar_ . (Argument  Prefix) 

data-search-path) . (LISP  Function) 

{eslalua  data-search-path  (s_directory  ...)) . (LISP  Function) 

(declare-hunk-typc  (s^type  (s_C-type  s_C-prefix]) . [LISP  Macro) 

(s_attribute-visibility] 

[has-ia-a-aiub-awitek  s«is-a-stub-switch] 

[haa-eomparc-axviteh  s_compar e-switch] 

[haa-format-awiteh  s_format-switch] 

[haa-uneval-awiteh  s.uneval-switch] 

(s_attribute-protection]  \haa-paaaword  s^password) 
[kaa-alloeation-eount  g_allocation-count] 
s_attribute-l 

(s_attribute-2  g_dcfault-value-2  (s_C- attribute- name-2]) 
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(declare- vector- type  (i^_iype  pe  s_C-prL*fiXi) . [LISP  Macro^  5-51 

hai^-allacalian'covvt  g_allocation-count] 

ha^-C-iijpc-rtcior-tkiucni-namt  s_C- type- vector- element- name’ 
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\h as- compare- switch  s^compare-switch] 
has-form at -switch  5_formai -switch] 
has-vneval-switch  5_uneval- switch] 

_s_ai  tribute- protect  ion]  [has-password  s^password] 

|.X-.repeai -count]  5_aMribut e- 1 

;\_repeat-count]  (s_attribute-2  g_default-value-2  [s«C-attribute-name-'2]) 


...) 

** default-array-element-type*  . [LISP  Global  Variable] 

*  default- array-file* . [LISP  Global  Variable; 

*default-array-long-exponent*  . [LISP  Global  Variable] 

*default-array-short-exponent* . [LISP  Global  Variable] 

*default-bitgraph-parameter-set* . [LISP  Global  Variable] 

*default-dither-size* . 

(defcache  s^function  (g_?ize  .s_equal  5_cachc)  Larguments . [LISP  Macro] 

.  Lbody) 


7-3 

7-38 

7-3 

7- 3 
9-1 

8- 6 
3-15 


(defconst  ...) . [LISP  Macro]  Erl 
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(dcfinc-object- name- prefix  ’s^prefix  ’s«f unction) . [LISP  Function]  5-59 

(define-type  ’s_name) . [LISP  Function)  5-59 

(define-vector-type  (list  ’s_type  [’s_C-type  's_C-prefix]) . (LISP  Function]  5-51 
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(defprop  ...). . [LISP  Macro] 

(defsetf  s_function  (s.expi  essioii  s«value) . [LISP  Macro] 
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(del2g-kernel  ’(n_xwidlh  n_y width) . [LISP  Function] 

[’(n_xoffset  n^yoffset)]) 

demo . (Make  Target] 

(demo  (’s_input-file  [/]  [’s_ouiput-file  [/]]]) . [LISP  Function] 

$(DEMO_CLFILESj . . (MaJvE  Macro] 

$(DEMO_LFILES) . [MAJvE  Macro] 

$(DEMO^LISP) . [MAKE  Macro] 

$(DEMO_LISZT) . [MAKE  Macro] 

$(DEMO_OUFILES) . \^\A1\E  Macro) 

$(DEMO^TARGET_FILES) . (MAlvE  Macro] 

(derivative-filter  ’lar^array  'x_diniension  ’x_widtli) . [LISP  Function] 

(difference-of-transforms  ’trans^tl  ’lrans_t2) . [LISP  Macro) 

(difTerence-of-vectors  ’vec_vl  ■vec_v2) . [LISP  Macro) 

dis_ . [Argument  Prefix] 

(dismount-tape  [’x_drive  ) . [LISP  Function] 

(dismount-tape  (*s_volume-name]) . (LISP  Function] 

‘'display  daemon’' . [SKETCH  Term] 

“display  protocol  ’ . (SICETCH  Term] 

“display  window  point” . (SIxETCH  Term] 

(display-bitgraph  ’ubar_array  ’s/Lname  (’dwin_window] . (LISP  Function] 
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(display-image  ’ar_array  [’dwin^window] . (LISP  Function] 
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[has-low  ’s_low-color] 

[has-high  ’s_high-color] 

’(x^xcontrast  x^ycontrast)] 

[do-pscudocotor  ’g_pseudocolor-switch]) 

(display-lines  (dwin_window]  [n^width] . (LISP  Function] 

[bpn_plane]  [trans_transform] 

(dwpt.point]  ...  (ni7]  ((]  ar_array]  ...) 
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'^display-map-map* . [LISP  Global  Variable] 

(display*patom  g.value  [‘(n^xorigin  n_yorigin)] . [LISP  Function] 

j’bpn^plane]  ps.adjusi  ...1  l’n_size^  1‘s.orientation]  j’dwin.winclow]) 

^display-plane-map*^ . [LISP  Global  Variable] 

(display-pretty-print  ’x.Iine-length  g.valut' . [LISP  Function] 

[’(n_xorigin  n_yorigin)^  ;’bpn_plane]  [’s_adjust  ...]  [’n_size] 
[’s.orientation]  [’dwin.window]) 

(display-print  ^g.value  [’(n.xorigin  n_yorigiii) . [LISP  Function] 

[’bpn.planej  [’s.adjusl  ...]  [’n.size]  [’s.orientalion]  [’dwin.window]) 

(display-text  (^x.line-length  ['(n^xorigin  n_yorigin)] . [LISP  Macro] 

[’bpn.plane]  [’s.adjust  ...]  ['n.size]  [’s.orientation]  [’dwin_window]) 
g.statement ...) 

(distance-between-lines  ’lin_line-l  Min_line-?) . [LISP  Macro] 

(distance-between-point-and-line  ’pt_poinl  ’lin.line) . [LISP  Macro] 

(distance-between-points  ’pt_pl  *pt_p*2) . [LISP  Macro] 

(dither  ’x.size) . [LISP  Function] 

$(DITROFF) . [MAKE  Macro] 

$(DITROFF_FLAGS) . . . . [MAKE  Macro] 

dmap_ . [Argument  Prefix] 

.do .  . . [UNIX  File  Extension] 

$(DOFILES) . [MAKE  Macro] 

(dpb  ’x_value  #oPPSS  ^x_number) . [LISP  Function] 

(dumplisp  s_file) . [LISP  macro] 

(duplicate-of- array  ’ar.array) . [LISP  Function] 

dwin_ . [Argument  Prefix] 

dwpt^ . [Argument  Prefix] 

(dxg-kernel  '(n_xwidth  n.ywidth) . [LISP  Function] 

[’(n.xoffset  n_yoffset)j) 

“edge  of  chain'* . [SKETCH  Term] 

elL . [Argument  Prefix] 

(environment  ...) . [LISP  Macro] 

(environment-lmlisp  ...) . [LISP  Macro] 

(cnvironment-maclisp  ...) . [LISP  Macro] 

$(EQN) . [MAKE  Macro] 

$(EQN .FLAGS) . [MAKE  Macro] 

(equal-filled-lists  'Llist-l  'I_listr2  *g_fill) . [LISP  Function] 

(equal-property- lists  'Llistrl  *Llistr2) . [LISP  Function] 

(equ al-p rope rty -1  is ts-w it h-sw itches  MJistrl  'Llistr2 . [LISP  Function] 

'IJnfo) 


(error  ’Lmessagc) . [LISP  Function] 

(error  ’s/t.message  ['g.data_l  [*g.data_2]]) . [LISP  Function] 

(error- trace  ’s.switch) . [LISP  Function] 

“evaluator” . [SKETCH  Term] 

.ex . [UNIX  File  Extension] 

ex.clean . [MAKE  Target] 

(cxccute-found-operation  ’opd.descriptor  'op.operation  ...) . [LISP  Macro] 

(execute-operation  'op.operation  'ob.object  ...) . [LISP  Macro] 

(execute-parent-operation  'opd.descriptor  'op.operation . [LISP  Macro] 

'ob.object  ...) 
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^exit-on-error*  . . [LISP  Global  Variable 

(expand-missmg  'lai'_outpiil  ni_inpiit  ’ar_original . (LISP  Function; 

p(x«xsize  x«y>ize)  ’x^count]]) 

(expand-missing-of  ’ar_inpin  ar_onginal . (LISP  Function] 

l’(x_X5izc  x.ysize)  [\_count  j\_repeat  ...]]]) 

(exponcntiate-array-elements  ’lar_output  j’larjnput]) . (LISP  Function] 

(expose-display  px_count]  pclis/d\vin_display]) . (LISP  Function] 

.f . (UNDC  File  Extension] 

. (Argument  Prefix] 

(f  (n^xorigin  n_yorigin)) . [Bitgraph  Program  Statement] 

far_ . (Argument  Prefix] 

(fdelay  ’f_time) . (LISP  Function] 

$(FFILES) . (MAKE  Macro] 

S(FILES) . (MAJvE  Macro] 

(filestat-atime  ...) . [LISP  Function] 

(filestat-ctime  ...) . [LISP  Function] 

(filestat-dev  ...) . (LISP  Function] 

(filestat-gid  ...) .  . [LISP  Functionj 

(filestat-ino  ...) . [LISP  Function] 

(filestat-mode  ...) . [LISP  Function] 

(filestat-mtime  ...) .  . (LISP  Function 

(fi lest at-n link  ...) . [LISP  Function] 

(filestat-rdev  ...) . [LISP  Function] 

(niestat-size  ...) . [LISP  Function 

(fi  lest  at- type  ...) . . [LISP  Function 

(filestat-uid  ...) . [LISP  Functionj 

(find-character-set  ’s_font  ’(n_xsize  n_ysize)) . (LISP  Function] 

*find-character-set* . (LISP  Global  Variable] 

(find-display-map  ’(s_map-name  (s_monitor  ...])) . [LISP  Function] 

(find-display-map  ’s_map-name) . (LISP  Function] 

(find-display-maps  ^(s_map*name  (s.monitor  ...])) . (LISP  Function] 

(find-display-maps  ’s_map-name) . (LISP  Function] 

(find-get-attribute-descriptor  ’atd_descriptor  ’at^attribute . [LISP  Function] 

*ty_type) 

(find-get-attribute-descriptor-for-macro  *g_descriptor  *g«attributc.(LISP  Function] 

’g-type) 

(find-operation-descriptor  ’opd_descriptor  *op«opcration  *ty_type) . (LISP  Macro] 

(find-operation-dcscriptor-for-macro  ’op  d_d  esc  rip  tor . (LISP  Function] 

’op^operation  *ty_type) 

(find-set-attribute-descriptor  ’atd_descriptor  *at_attribute . [LISP  Function] 

’ty.type) 

(find-set-attribute-descriptor-for-macro  ’g_descriptor  ’g_attribute.[LISP  Function] 


float-format . . [LISP  Global  Variable] 

(floor  n^number) . (LISP  Function] 

(flush-display  [’f^delay]  (’dis/dwin«display]  [t]) . (LISP  Function] 

forever . (C  Macro] 

(format-object  ’ob_object  ’x_level) . [LISP  Macro] 

(format-object  ’ar_array  ...) . (LISP  Function] 
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franz-version. . .  . . . [LISP  Global  Constant; 

FR.CAMERA  . [C  Macro; 

FR_CAMERA  caniera_string_size  camera.siring.[SIvETCH  Display  Daemon  Requestj 

FR.CLEAR . . [C  Macro] 

FR_CLEAR  xorigin  yorigin . [SKETCH  Display  Daemon  Requesij 

xsize  ysize  pixeLvalue 


FR^CLOSE . [C  Macro] 

FR_CLOSE . [SIvETCH  Display  Daemon  Requestj 

FR_CLOSE  . . [SIvETCH  Display  Daemon  Response] 

FR.ERROR . . [C  Macro] 

FR_ERROR  message_size  message_string . [SKETCH  Display  Daemon  Requestj 

FR_FLUSH . [C  Macro] 

FR_FLUSH  delay_time  exposure_coiint . [SKETCH  Display  Daemon  Request) 

FR_FLUSH . (SICETCH  Display  Daemon  Response] 

FR.MAP . [C  Macro] 

FR_MAP  xsize  ysize  map_iype  map_sti‘ing . [SIvETCH  Display  Daemon  Requestj 

FR_NOP . ’ . [C  Macro] 

FR_NOP . [SKETCH  Display  Daemon  Request] 

FR_NOP . [SKETCH  Display  Daemon  Response! 

FR_OPEN . [C  Macro] 

FR_OPEN  U5er_id_$ize  device_size . [SKETCH  Display  Daemon  Request] 

processor_size  monitor_size  camera_sizc 
user_id_string  device_string 
processor_string  monitor_string  camera_string 

FR_OPEN . [SIvETCH  Display  Daemon  Response) 

FR.WRITE . * . [C  Macro] 

FR_WRITE  xorigin  yorigin . [SKETCH  Display  Daemon  Request] 

xsize  ysize  psize  pixel_string 


(ftime) . [LISP  Function] 

g_ . [Argument  Prefix] 
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’^gc-count* . [LISP  Global  Variable] 

^gc-dumpfile*^ . [LISP  Global  Variable] 

'^gc-errors* . [LISP  Global  Variable] 

^gc-history*^ . [LISP  Global  Variable] 

*gc-history-lcngth* . [LISP  Global  Variable] 

(gcntemp) . [LISP  Function] 

(get-abnormal-attributes  [do-rttnm-really-ni(\ . [LISP  Function] 

*{ty_type  at_attribute-l  g_value-l  ...) 

*at_attribute-ll  *at_attribute-12  ...) 

(get-attribute  ’at_attribute  *ob_object  ...) . [LISP  Macro] 

(get-attribute-descriptor  *atcLdcscriptor) . [LISP  Function] 

(get-catalog-keys  ’ca^ndex-catalog) . [LISP  Function] 

(get-catalog-location  ’ca^catalog) . [LISP  Function] 

(get-character-bitgraph  *csct_character-set  *s/x_character . [LISP  Function] 

[*s_oricntation]) 

(get-character-display  *cset_charactcr-set  *s/x_character) . [LISP  Function] 
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(get-current-display- window) .  (LISP  Macro] 

(get-default-value  ’at.aitribute  ’ty^type  |'ai<Ldescripiorj) . [LISP  Function] 

(get- format-switch  at^attribute  ‘ty^type  [’aid_de5ci*iptorj) . (LISP  Function] 

(get-found-attribute  ’atd^descriptor  ’at_aUribute . [LISP  Macro] 

'ob_object  ...) 

(get-is-a-stub-switch  *at_attribute  ’ty^type  [’ald_descriptor]) . [LISP  Function] 

(get-operation-descriptor  ’opd_descriptor) . [LISP  Function] 

(get-parent- attribute  ’atd_descriptor  ’at_attribute . [LISP  Macro] 

^ob_object  ...) 

(get-playback- display-window) . [LISP  Macro] 

(get-random-port  ’p_port  (*g_location  ’s.direction . [LISP  Function] 

[’(s_directory-name  ..  )]]) 

(get-random-port-location  *p_port) . [LISP  Function] 

(get-switch-from-info  *at_attribute  *l_info  s_switch) . [LISP  Macro] 

(get-sw itch- info  ’ty_type  ’(atd_descriptor  ...) . [LISP  Function] 
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SOB.SYMBOL . [C  Global  Variable]  5-79 

8ob_tsiae  (ty_type) . [C  Function]  5-81 

SOB.TYPE . [C  Global  Variable]  5-79 

8ob_type . [C  Type]  5-81 

SOB.UBIT . [C  Global  Variable]  5-79 

SOB.UCHAR . [C  Global  Variable]  5-79 

SOB.ULONG . [C  Global  Variable]  5-79 

SOB_UNSIGNED . [C  Global  Variable]  5-79 

SOB.USHORT . (C  Global  Variable]  5-79 

SOB.VALUE . [C  Global  Variable]  5-79 

8ob_vcreat€  (ty_type) . [C  Function]  5-81 

8ob_vinit  (ob_object  ty_type) . [C  Function]  5-81 

${SOURCE_FILES) . (MAKE  Macro]  C-50 

•sp . (UNIX  File  Extension]  C-51 

sp. clean . [MAKE  Target]  C-28 

$(SPELL) . [MAKE  Macro]  C-51 

spell . [MAKE  Target]  C-51 

$(SPELL_FLAGS) . [MAKE  Macro]  C-51 

(split-filename  ’s_file) . (LISP  Function]  3-27 

sqrt-pi . [LISP  Global  Constant]  3-20 

(square-root-array-elements  ’lar_output  [’lar_input]) . [LISP  Function]  8-14 

(stringopen  ’t_string  ’x_size  ’s/t_mode  [’t_name]) . [LISP  Function]  3-27 

“stub” . [SKETCH  Term]  5-82 


Printed  May  1,  1989 


SKETCH  INDEX 


A.34 


(subtract- arrays  lar.output  plar_input-l]  ’lar_input-2) . [LISP  Function] 

(sum-filter  ’lar^array  ’x_dimension  \_widih) . [LISP  Function] 

(summary-of- array  ’ar_array] . [LISP  Function] 

(sum-of-transforms  *trans_tl  ’trans_t2) . [LISP  Macro] 

(sum-of-vectors  ’vec_vl  *vec_v2) . [LISP  Macro] 

(sweep- array-blocks) . [LISP  Function] 

*sweep-array-blocks- bytes* . (LISP  Global  Variable] 

*sweep-array-blocks-count* . [LISP  Global  Variable] 

*8weep-array-blocks-time* . [LISP  Global  Variable] 

(symbol-init-function  *g_value . [LISP  Function] 

*atd_descriptor  'at_attribute  ’ty_type) 

(symbol-init-macro  'g_value . [LISP  Macro] 

atd^descriptor  at_attribute  ty^type) 

(symeval  ’s^symbol) . [LISP  Special  Function] 

T . . . [C  Local  Variable] 

(t  [n_character-sizel . [Bitgraph  Program  Statement] 

[s_hoi*izontal-adjust|  }s_vertical-adjust] 

[s_orientatioiv  (n_xorigin  n_yorigin)  5/t_string  ...) 

$(TBL) . . ! . (MAKE  Macro] 

$(TBL.FLAGS) . [MAICE  Macro] 

T-dimension . [LISP  Global  Constant] 

$(TITLE) . . [MAKE  Macroj 

*top-level-eval*  . . [LISP  Global  Variable] 

*tof>-level-exit*.  . [LISP  Global  Variable] 

*top-level-init* . (LISP  Global  Variable] 

*top-level-init-started* . (LISP  Global  Variable] 

*top-level-init-times* . (LISP  Global  Variable] 

*top-level-print* . [LISP  Global  Variable] 

*  top- level-print* . [LISP  Global  Variable] 

*top-level-print-times* . [LISP  Global  Variable] 

*  top- level- prompt* . [LISP  Global  Variable] 

(sstatus  top- level- rc-files  (s_rc-file  ...)) . [LISP  Function] 

(status  top-level-rc-files) . [LISP  Function] 

*  top- level- read* . [LISP  Global  Variable] 

*top-level-saved-print^times* . [LISP  Global  Variable] 

*top-level-saved-times* . [LISP  Global  Variable] 

(sstatus  top-level-switches  (s^switch  ...)) . [LISP  Function] 

(status  top- level-switches) . [LISP  Function] 

*top-lcvel-threshold-time* . [LISP  Global  Variable] 

*top-level-times* . [LISP  Global  Variable] 

.tr . [UNIX  File  Extension] 

trans. . [Argument  Prefix] 

(transform- covector  ’trans.transform  Vec.vector) . [LISP  Macro] 

(transform-line  Min^line  ’trans^transform) . [LISP  Function] 

(transform-point  *pt_point  ’trans_transform) . [LISP  Macro] 

(transform-vector  ’vec_vector  *trans« transform) . [LISP  Macro] 

(transpose-array  ’ar_array  ’x_dimension-l  ’x_dimension-2) . [LISP  Function] 

(transpose-transform  *trans_transform) . [LISP  Macro] 

tr.clean . [MAKE  Target] 
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.tv . [UNIX  File  Extension] 

ty_ . [SIvETCH  Argument  Prefix] 

ty« . (Argument  Prefix] 

(s_type  *at_attribute  ’g^value  ...) . [LISP  Macro] 

(s^type  *ob_object) . [LISP  Macro] 

(s_type  ’ob_object  *at_attribute  *g_value  ...) . [LISP  Macro] 

U . . [C  Local  Variable] 

ubar_ . {Argument  Prefix] 

ucar_ . [Argument  Prefix] 

uchar . [C  Type] 

U-dimension . [LISP  Global  G^nstantj 

ular_ . [Argument  Prefix] 

ulong.. . [C  Type] 

ulx_ . [Argument  Prefix] 

(unevaLobject  ’g_object . [SKETCH  Operation  Macro] 

[^g Jnde.x-switch  [’g_back quote-switch]]) 

uneval-object . [SI\£TCH  Operation] 

(uneval-object  ’ar_array  [/]) . [LISP  Function] 

(unit-transform  ’x_dimension) . [LISP  Macro] 

(unit-vector  ’x_unit-dimension  \_total-dimension) . [LISP  Macro] 

(unpre-evaluate-object  ’ob_object) . [LISP  Function] 

usar_ . [Argument  Prefix] 

(use-ptport  *p_port) . [LISP  Function] 

ushort . [C  Type] 

ux_ . [Argument  Prefix] 

V . [C  Local  Variable] 

V-dimension . [LISP  Global  Constant] 

vec_ . [Argument  Prefix] 

(vector-product^of-vectors  ’vec_vector-l  ’vec_vector-2) . [LISP  Macro] 

(vectors-are-parallel  Vec_vector-l  *vec_vec tor-2) . [LISP  Macro] 

veCty_ . [Argument  Prefix] 

.VO . . [UNIX  File  Extension] 

(vrefi-double  ’V^vector  ’x_index) . [LISP  Special  Function] 

.vs . [UNIX  File  Extension] 

vs. clean . [MAKE  Target] 

(vsise-double  V_vector) . [LISP  Function] 

(vsize-long  V^vector) . [LISP  Function] 

$(VSJ>RINT) . [MAKE  Macro] 

$(VS  J>RINT  .FLAGS) . [MAKE  Macro) 

(w  (n^xsize  n.ysize)  (n.xorigin  n.yorigin) . [Bitgraph  Program  Window] 

(n.xzoom  n.yzoom)  s.orientation  < statement >  ...) 

wc . [MAKE  Target] 

WC . [MAKE  Target] 

WC . [UNIX  File  Name] 

(write- array-elements  *ar.array  *g.array-filc) . [LISP  Function] 

(write-catalog  *caL.catalog  ’g_value) . [LISP  Function] 

(write-catalog  *caL.catalog  ’ar.array) . (LISP  Function] 

(write-display  ’ca_catalog]  [*dis/dwin.display]) . [LISP  Function] 

x_ . [Argument  Prefix] 
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X . [C  Local  Variable] 

X-dimension . [LISP  Global  Constant] 

xp . [C  Local  Variable] 

(xtime  *g_expression) .  [LISP  Function] 

Y . [C  Local  Variable] 

Y-dimcnsion . [LISP  Global  Constant) 

Z . [C  Local  Variable] 

Z-dimension . [LISP  Global  Constant] 

(^era-edges  *ar_ edges  Mar^input  px_resoluLion]) . [LISP  Function] 

(rero-cdgca-of  ’ar«input  ^(x_x width  x_y width) . [LISP  Function] 

[\«resolution]) 

(rero-edge-strength-of  *lar_outpui  *lar_input . [LISP  Function] 

n artwork  ’ar.edges) 

(zero- transform  ’x_dimension) . [LISP  Macro] 

(sero-vector  ’x^total-dimension) . , . [LISP  Macro] 
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1.  DESCRIPTION  The  files  in  this  package  are  those  likely  to  be  changed  when  mov¬ 
ing  from  one  hardware/software  operating  system  to  another.  For  example,  all  names  of 
directories  outside  SKETCH  are  in  the  files  of  this  package. 

When  porting  SKETCH  to  a  new  system,  the  source  files  of  this  package  should 
always  be  read  and  modified  as  necessary.  Some  of  these  files  are- 


scojoad.l 

Loaded  into  SKETCH  evaluators,  but  not  compilers. 

sco compile.l 

Loaded  into  SKETCH  compilers,  but  not  evaluators. 

sco common.l 

Loaded  into  both  SKETCH  evaluators  and  compilers. 

sco globaLh 

Same  as  FRANZ  h /global. h,  with  additions  to  keep  lint  happy. 

sco_defsl.mk 

Included  in  every  SKETCH  makefile. 

See  NL\K1NG  FILES  Appendix. 

The  names  defined  in  these  files  are  parts  of  other  packages,  and  are  therefore  docu¬ 
mented  elsewhere. 

Some  of  the  contents  of  these  files  may  be  overridden  by  /op-ZcvcZ-rc-nVcs,  which  are 
usually  files  with  the  name  sketch. rc  or  sketchcom.rc  in  the  current  directory,  parent 
directories  of  the  current  directory,  or  users  home  directory.  See  top-level-rc-files 
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1.  MAKING  TARGET  FILES  FROM  SOURCE  FILES.  The  SKETCH  make 
package  facilitates  the  making  of  files  from  other  files,  for  example  the  making  of  foo.o 
from  foo.c.  All  that,  is  necessary  to  enable  SKETCH  make  is  to— 

(1)  Create  a  directory  for  the  package  (set  of  related  functions)  you  are  writing.  This  is 
called  the  package  directory.  Usually  several  related  package  directories  are  sub¬ 
directories  of  a  common  directory  called  a  global  directory.  The  global  directory 
has  to  be  built  properly,  but  this  will  usually  have  already  been  done:  see  GLOBAL 
DIRECTORIES  below  * 

(2)  Put  an  executable  (x  permission  set)  file  named  make  in  this  directory  which  has  the 
form  — 

#!  bin  Vsh  — f 
if  (— r  csh.rc)  then 

source  csh.rc 
else  if  (— r  ../csh.rc)  then 
source  ../csh.rc 

else 

source  ../../csh.rc 
endif 

exec  psearch  smk/smk_make.sh  $argv:q 
A  typical  value  for  ../csh.rc  in  the  global  directory  is— 

set  path={.  /ul/walton/sketch4/users  /sketch/sketch4b/ll/sun3.5  \ 

/sketch/sketch4b/ll/sun3.5/tps  /usr/local/bin  /usr/ucb  /usr/bin  /bin) 

rehash 

setenv  CPP_PATH  I/ul/walton/sketch4/users  — I/sketch/sketch4b/ll/sun3.5*' 
setenv  COMPUTER^TYPE  sun3 

This  combination  of  make  and  csh.rc  establishes  a  path  of  global  directories  that 
may  be  searched  for  names  of  the  form  — 

<  pac  k  age_n  ame>/<filename>. 

Psearch  (which  is  part  of  the  TPS  system:  see  TEAM  PROGRAMMER  SYSTEM 
below)  performs  such  a  search  for  the  smk/smk^make.sh  program,  which  executes 
the  make  command  for  a  SKETCH  package  directory. 

(3)  Put  into  the  package  directory  a  file  named  makefile. mk  which  might,  for  example, 
be  the  following— 

CFILES=foo.c 
LFILES=bar.l 
OFlLES=foo.o  bar.o 
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This  file  defines  make  inacios  named  CFILES  and  OFILES.  Macro  definitions  for 
make  consist  of  llie  macro  name,  followed  by  an  equal  sign,  followed  by  the  charac¬ 
ter  string  to  which  the  macro  is  being  defined,  followed  by  the  end  of  line  (continua¬ 
tion  across  lines  is  allowed  by  using  the  backslash  \  before  the  line-ends  that  are  to 
be  ignored). 

CFILES  is  a  list  of  all  the  .r  source  files  in  the  package;  LFILES  a  list  of  all  ./source 
files;  and  OFILES  a  list  of  all  the  .0  target  files.  It  is  the  job  of  make  to  make  target 
files,  wdiich  do  not  initially  e.visl.  from  source  files,  which  are  typically  text  files 
edited  by  the  programmer. 

(4)  You  may  now  make  the  target  files  from  the  source  files  by  UNIX  commands  such 
as— 

make  foo.o 
make  bar.o 
make  foo.o  bar.o 
make  all 
make 

The  first  two  commaiuL  make  only  one  of  the  files,  the  one  designated  The  third 
command  makes  both  files  'J'he  la.si  two  commands  make  all  the  target  files  listed 
in  makefile. mk.  This  is  because  making  the  target  all  is  defined  to  be  the  same  as 
making  all  the  files  listed  in  the  .4LL_r/L£’5 macro,  which  by  default  is  defined  by  — 

ALLSILES=%[LHFILES)  ^OFILES)  %{FILES)  \ 

$(  0  THER_  TA  R  GE ILFILES) 

Also,  make  by  itself,  with  no  target  mentioned,  is  defined  to  be  equivalent  to  making 
the  target  all. 

Note  that  make  macros  are  invoked  by  the  form  — 

$(  <  macro-name  >) 

The  macros  LHFILES,  FILES,  and  OTHER^TARGETJFILES,  not  having  been  defined  in 
our  makefile. mk,  are  defined  to  be  null  strings. 

The  make  command  makes  target  files  by  executing  UNIX  commands.  It  prints 
these  commands  out  just  before  executing  them.  Thus  the  following  is  typical— 

%  make  foo.o 
rm  — f  foo.o 

cc  — O  — I/ul/>valton/sketch4/users  — l/sketch/sketch4b/ll/sun3.5  — c  foo.c 
chmod  a— w  foo.o 
%  make  bar.o 
rm  -f  \#bar.\# 

sketchcom  —q  bar.  I  — o  \#bar.\# 
chmod  a— w  \^bar.\# 
mv  -f  \#bar.\#  bar.o 

If  you  give  make  the  — n  option,  as  in  "make  —n  alt',  it  will  print  the  UNIX  com¬ 
mands  it  would  execute  to  make  the  target  files,  but  will  not  execute  these  commands. 
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The  wake  commviiul  also  pays  attention  to  some  subtleties— 

(1)  It  will  not  make  foo.o  if  that  file  exists  and  hajs  a  creation  date  later  than  foo.c. 
Instead  it  will  either  print— 

‘foo.o’  is  up  to  date. 

if  you  explicitly  asked  for  foo.o  as  a  target,  or  do  nothing  if  foo.o  was  an  implicit 
target  (as  when  all  is  the  explicitly  asked  for  target). 

Similarly  if  bar.o  exists  and  has  a  creation  date  later  than  bar.l. 

(2)  SKETCH  make  will  usually  change  the  files  it  makes  to  be  read-only.  This  indicates 
to  the  backup{l{ps)  program  whose  use  is  described  under  INSTALLING  PUBLIC 
VERSIONS  below  that  the  files  are  not  changeable  (but  may  be  deleted  and 
replaced),  and  therefore  it  is  safe  to  link  to  these  files  rather  than  waste  disk  space 
by  copying  them. 

SKETCH  moke  will  use  ’’r/n  — and  — /'*  to  remove  previous  copies  of  target 

files  in  order  to  avoid  protection  problems  when  these  previous  copies  are  read-only. 

(3)  SKETCH  make  will  take  pains  to  avoid  leaving  erroneous  target  files  around  when 
there  is  an  error  in  making  a  target  file.  This  is  why  the  target  file  is  often  made 
under  a  pseudonym  such  as  #bar.#  above,  and  mx''ed  to  its  final  name  only  after  it 
has  been  correctly  made.  (The  backslashes  \  in  front  of  the  #’s  in  the  printed  make 
output  disappear  when  the  command  is  read  by  the  UNIX  shell:  they  are  necessary 
because  #  without  \  is  a  comment  character  to  the  UNIX  mak€{\)  program.) 

(4)  Simple  UNIX  commands  such  as  cc  may  not  work  for  SKETCH,  and  may  have  to  be 
replaced.  For  example,  in  one  system  a  compiler  table  was  too  small  to  handle  the 
large  C  language  for  loops  used  in  SKETCH,  so  an  alternative  version  of  the  com¬ 
piler  was  constructed  and  cc  was  replaced  by— 

cc  — B/sketch/sketch4b/berkeley/vax4.3/pcc/  — tO 

2.  PACKAGE  DEFINING  MACROS.  To  define  a  package  you  define  macros  in 
makefile. mk.  Table  1  describes  the  macros  most  commonly  used  for  this  purpose. 
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TABLE  1:  PART  1 

PACKAGE  DEFINING  MACROS 

Macro  Name 
"Default  Value" 

Definition 

CHAPTER 

ft  It 

The  chapter  number,  or  appendix  letter,  of 
the  package  documentation  chapter  or  ap¬ 
pendix. 

PREFIX 

•  f  ft 

A  several  letter  prefix  that  appears  a  the  be¬ 
ginning  of  most  file  names  and  C  language 
global  names  in  the  package.  Some  exam¬ 
ples;  ‘sink’,  ‘sob’,  and  ‘sar’.  The  prefix  is 
separated  from  the  rest  of  a  name  by  an 
underline.  Some  example  file  names: 
‘sarjisp’.  ‘sob^tvpe.r.  and  ‘smk.defsl.mk’. 

PACKAGE_DIRECTORY 

"%lPREFIXr 

This  is  the  name  of  the  package  directory 
within  ils  containing  global  directory.  Nor¬ 
mally  this  equals  the  package  prefix,  but  it 
does  not  have  to. 

TITLE 

lift 

The  title  of  the  package’s  documenting 
chapter  or  appendix. 
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TABLE  1:  PART  2 
PACKAGE  DEFINING  MACROS 


Macro  Name 

Definition 

"Default  Value" 

LISP 

"^fSKETCHf 

The  LISP  evaluator  environment  into  which 
.0  files  of  this  package  are  to  be  loaded  to 
produce  an  evaluator  environment  for  users 
of  this  package.  Defaults  to  %{SKETCH), 
which  in  turn  defaults  to  the  SKETCH 
evaluator  program. 

DEMO_LISP 

''$(LISP)  -I  %(PREFIX)Joa(r 

The  LISP  evaluator  environment  which  is 
used  to  make  an  .ou  file  from  a  ./  file  by  run¬ 
ning  the  demo  function.  Defaults  to  %{LISP) 
with  the  evaluator  files  of  this  package  load¬ 
ed  in  by  a  —/switch. 

LISZT 

"%(SKETCHCOMf 

The  LISP  compiler  environment  into  which 
.0  files  of  this  package  are  to  be  loaded  to 
produce  a  compiler  environment  for  users  of 
this  package.  Defaults  to  ^SKETCHCOi\f), 
which  in  turn  defaults  to  the  SKETCH  com¬ 
piler  program. 

DEMO_LISZT 

"%(LISZT)  -/  %(PREFIX)_compile 

The  LISZT  compiler  environment  which  is 
used  to  make  a  .ou  file  from  a  .cl  file  by  run¬ 
ning  the  demo  function.  Defaults  to 
%{LISZT)  with  the  complier  files  of  this 
package  loaded  in  by  a  —/switch. 

CFELES 

All  .c  source  files  in  the  package.  These  are 
the  C  language  files. 

Printed  May  1,  1989 


MAKING  FILES  C-6 


TABLE  1:  PART  3 
PACKAGE  DEFINING  MACROS 


Macro  Name 

Definition 

"Default  Value" 

COMMONJLFELES 

ttt« 

All  ./  source  files  in  the  package  that  are  to  be  loaded  into 
both  the  LISP  evaluator  environment  and  the  LISP  com¬ 
piler  environment.  See  COMPILE_LFILES, 

LOAD LFILES,  and  OTHER LFILES. 

COMPILEJLFILES 

tf  t« 

All  ./  source  files  in  the  package  that  are  to  be  loaded  into 
the  LISP  compiler  environment,  but  not  the  LISP  evaluator 
environment.  See  COMMON_LFILES,  LOAD_LFILES, 
and  OTHER LFILES. 

CSFILES 

tttt 

All  .cs  source  files  in  the  package.  These  files  are  written  in 
a  combination  of  assembly  language  and  C  macro  language. 

DEMO.CLFILES 

ttti 

All  .cl  source  files  in  the  package  that  are  demonstration 
programs  to  be  run  by  the  compiler  %(DEMO^ISZT)  (and 
not  the  evaluator). 

DEMOJLFILES 

tttt 

All  ./  source  files  in  the  package  that  are  demonstration 
programs  to  be  run  by  the  evaluator  %(DEMO LISP). 

DEMO_OUFILES 

tttt 

All  .0X1  target  files  in  the  package  that  are  the  output  of 
demonstration  programs.  These  files  are  made  by  running 
./  files  through  the  evaluator  %(DEMO^ISP)  or  .cl  files 
through  the  the  compiler  %(DEMO_LISZT)  and  saving  the 
standard  output. 

DOFILES 

ittt 

All  .do  source  files  in  the  package.  These  are  documenta¬ 
tion  files  that  are  processed  by  cqn{l),  pic(l),  and 

IrofUl)  to  produce  miscellaneous  documentation. 
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TABLE  1:  PART  4 
PACKAGE  DEFINING  MACROS 


Macro  Name 

Definition 

"Default  Value" 

FFILES 

Ail  ./source  files  in  the  package.  These  are  the  FOR¬ 
TRAN  language  files. 

FILES 

«!•« 

All  target  files  with  no  extension  in  the  package. 
%(PREFIX)^lisp  and  %(PREFIX)^liszi  should  be  listed 
here  if  they  are  required  by  users  of  the  package.  If 
any  other  files  are  listed,  explicit  instructions  for  mak¬ 
ing  them  must  be  included  in  makefile. mk. 

HFILES 

ttfl 

All  .h  source  files  in  the  package.  These  are  C  language 
files  that  are  i^mclude^d  in  other  c  files,  and  do  not 
themselves  have  any  corresponding  .0  file. 

INSTALL.  RCFILES 

tttt 

All  .rc  source  files  that  are  to  be  installed  in  the 
%(INSTALL^DIRECTORy)  (defined  as  a  UNIX  en¬ 
vironment  variable  in  csh.rc)  by  the  install  command. 

LCFILES 

tttt 

All  .Ic  source  files  in  the  package.  These  are  C 
language  files  written  with  special  conventions  that 
make  them  directly  callable  by  LISP  code.  These  files 
are  also  compiled  in  a  special  manner. 

LHFELES 

•  tit 

All  .Ih  target  files  in  the  package.  These  are  C 
language  files  that  are  created  from  ./  files  that  use  the 
declare-hunk’type  or  declare-vector~type  functions  from 
the  SKETCH  Objects  Package.  These  files  are  then 
#include^d  into  .c  files. 

LIBRARIES 

ItM 

A  list  of  the  libraries  to  be  searched  by  ld[l)  after  other 
files  in  this  package  are  loaded.  Used  when  making  .ex 
files,  but  not  when  loading  .0  files  into  LISP  environ¬ 
ments. 

LNFILES 

tttt 

All  symbolic  link  files  defined  in  this  package. 
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TABLE  1:  PART  5 

PACKAGE  DEFINING  MACROS 

Macro  Name 
"Default  Value" 

Definition 

LOAJ)_LFILES 

Ifit 

All  ./  source  files  in  the  package  that  are  to  be  loaded  into 
the  LISP  evaluator  environment,  but  not  the  LISP  compiler 
environment.  See  COMPILE_LFILES, 

COMMON LFILES.  and  OTHER LFILES. 

MAFILES 

All  .njG  source  files  in  the  package.  These  are  documenta¬ 
tion  files  that  are  processed  by  cgn(l),  pic(l),  tbl,  and 
Iroflll)  to  produce  the  package  chapter  or  appendix. 

MKFILES 

"viakefile.inh" 

All  .///A' source  files  in  the  package.  These  are  input  to  tnake 
commands.  In  most  packages  there  is  only  one  such  file: 
nidkcfilc.wk. 

OFILES 

lilt 

.All  .0  target  files  in  the  package.  These  may  be  loaded  into 
LISP  environments,  or  combined  by  Id  to  produce  execut¬ 
able  programs. 
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TABLE  1:  PART  6 
PACKAGE  DEFINING  MACROS 


Macro  Name 

Definition 

’’Default  Value” 

OTHER_CLFILES 

All  .cl  source  files  in  the  package 
that  are  not  listed  in 

%(DEMO CLFILES). 

OTHER_DEMO_TARGET_J'ILES 

All  target  files  not  made  by  all  that 
are  to  be  made  before  making 
%(DEMO^OUFILES).  For  exam¬ 
ple,  foo.o  might  be  listed  if  it  is  to 
be  made  from  foo.l  before  a 
demonstration  program  is  run 

O  THER_IN  S  TALL_S  OURCE_FILES 

All  source  files  that  are  to  be  in¬ 
stalled  in  the 

%(INSTALL^DIRECTORY)  by  the 
install  command,  and  which  are  not 
already  listed  in  %(HFILES), 
%(SHFILES),  %(DEMO^LFILES), 
%(DEMO_CLFILES),  or 

%(INSTALLJiCFILES),  and  which 
are  not  one  of  the  two  files  make  or 
makefile. mk. 

OTHER_INSTALL_TARGET_PILES 

tttt 

All  target  files  that  are  to  be  in¬ 
stalled  in  the 

%(INSTALLJ)IRECTORY)  by  the 
install  command,  and  which  are  not 
already  listed  in  %(LHFILES),  and 
which  are  not  one  of  the  two  files 
tfPREFIXLchap.in  or  COUNT. 
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TABLE  1:  PART  7 

PACKAGE  DEFINING  MACROS 

Macro  Name 
"Default  Value" 

Definition 

OTHER_LFILES 

till 

All  ./  source  files  in  the  package  that  are  not  to  be 
loaded  into  either  the  LISP  evaluator  environment 
or  the  LISP  compiler  environment.  See 
COMPILE_LFJLES,  COMMONJjFILES,  and 
LOAD^LFILES. 

OTHER_RCFILES 

All  .rc  source  files  not  listed  in 

%(INSTALL R  CFILES). 

OTHER_SOURCE_FILES 

"make' 

Source  files  not  listed  elsewhere.  Usually  this  con¬ 
sists  of  shell  files  with  no  extension,  including  the 
wake  file  which  is  in  every  SKETCH  package  direc¬ 
tory. 

OTHER_TARGET_FILES 

Target  files  not  listed  elsewhere. 

SHFELES 

tttt 

AW  .sb  source  files  in  the  package.  These  are  writ¬ 
ten  in  either  the  sh{\)  or  csh{l)  language. 

3.  PROGRAM  CODE  FILE  EXTENSIONS.  The  extension  of  a  file  must  tell  the 
language  or  format  of  the  file  and  its  role  in  the  scheme  of  making  files  from  other  files. 
For  this  reason  SKETCH  make  uses  a  large  number  of  distinctive  file  name  extensions. 

Figure  1  indicates  the  file  extensions  and  make  paths  involved  in  making  .0  files  that 
are  loaded  into  lisp  and  its  derivatives  {lisztj  sketchy  and  sketchcom). 

C'r(l),  ltszt(l)f  /77(1),  and  as{l)  are  standard  UNIX  programs,  and  .c,  ./,  ./,  .5,  and  .0 
are  standard  UNIX  file  extensions,  /lib/cpp  is  the  C  language  macro  pre-processor,  which 
simply  substitutes  macros  in  the  input  text,  but  does  no  other  part  of  C  language  compi¬ 
lation.  Thus  .c$  files  may  use  C  macros  in  assembly  language  code.  The  strange  combi¬ 
nation  of  programs  used  to  process  Ac  files  have  almost  the  same  effect  as  cc,  but  make 
certain  substitutions  in  the  assembly  language  code  (using  fixmask  and  5e<i(l))  before  it  is 
passed  through  the  C  language  optimizer  /lib/c£.  These  substitutions  are  required  to 
write  FRANZ  LISP  lambda  functions  directly  in  C  on  the  VAX  (currently  these  substitu¬ 
tions  are  not  done  on  the  SUN). 

Figure  2  indicates  the  file  extensions  and  make  paths  involved  in  making  .ex  files 
that  are  directly  executable.  This  figure  is  almost  the  same  as  Figure  1.  One  difference  is 
that  cc(l)  is  used  to  make  the  .ex  files  from  the  .0  files.  In  this  use,  cc  merely  calls  the 
UNIX  loader,  W(l),  adding  a  program  startup  file  to  be  beginning  of  the  list  of  files  loaded 
or  libraries  searched,  and  adding  the  standard  C  library  to  the  end  of  this  list.  The  other 
difference  is  the  A  and  Ac  are  made  into  .ex  files  not  by  compilation,  but  rather  by  loading 
them  into  sketch  or  sketchcom  and  doing  a  dumplisp.  The  A  and  .cl  files  are  supposed  to 
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load  other  pre-compiled  files  and  set  global  variables  before  the  dumplisp. 

Note  that  the  autorun  facility  of  lisp{\)  (the  —r  option  to  liszt)  is  not  supported,  but 
similar  effects  can  be  obtained  by  writing  shell  files  and  using  the  -/and  -E  flags  provided 
by  the  FRANZ  EXTENSIONS  package:  see  top-level-switches  in  that  package. 

Lint  output  is  produced  in  the  form  of  .nt  files  just  like  compilation  produces  .s  files. 
See  Figure  3.  Lxnt.sh  is  a  shell  file  that  runs  the  standard  UNIX  lint  program  but 
removes  certain  meaningless  warning  messages  from  the  output,  so  that  the  goal  of  lint- 
ing  with  no  messages  is  reasonable. 

C  compilations  depend  upon  .h  files  as  well  as  .c  files.  A  Ah  file  is  similar  to  a  .A  file, 
but  is  made  from  a  A  file  by  the  process  of  Figure  4.  See  declar e-hunk- type  and  declare- 
vector-type  in  the  SKETCH  OBJECTS  Package  for  an  explanation  of  what  is  output  into 
*C-definition-code-port  *. 

If  a  .c  file  is  changed  after  its  corresponding  .0  file  is  made^  then  the  .0  file  will  be 
remade  the  next  time  it  or  all  is  made.  However  the  same  is  not  true  if  a  .h  or  Ah  file  on 
which  the  .0  file  also  depends  is  changed.  When  .h  or  .Ih  files  are  changed,  any  .0,  .s,  or 
.nt  files  that  depend  upon  them  must  be  removed  by  hand.  One  could  avoid  this  if  one 
wanted  to  by  adding  a  line  such  as— 

<filel>.o  <filel>.s  <filel>.nt:  <file2>.h  <file3>.lh 

to  makefile. mk,  thus  explicitly  giving  the  dependency  involved.  However,  if  a  change  is 
made  to  <file2>.h  which  will  not  effect  <filel>.o,  this  line  would  force  the  unnecessary 
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echo 
”fprogn 

(load  '  .1)  fgc) 

(duwplisp  <f]\e>  .ex)J 
sketch 


echo 

"(progn 

(load  '  <f\\e>  .cl)  (gc) 
(dumpUsp  <file>.exy/* 
I  sketchcom 


FIGURE  2:  MAKING  .ex  FILES 


.Ic 

LISP  C  language  j 


source 


FIGURE  3:  MAKING  .nt  FILES 
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*'f$€tq  ^C-definition-code-port* 

foulfile  ’<file  name>.//ij/* 
**fload  ’<file  name>.//' 

"(close  *C~definition'Code-port *f 
I  skelclicoin 


FIGURE  4:  MAKING  .Ih  FILES 

recompilation  of  <filel>.o.  Since  one  change  to  a  Ji  file  often  affects  only  a  few  of  the  o 
files  that  depend  on  the  Ji  file,  it  is  usually  more  efficient  to  remove  .0  files  by  hand  when 
a  Ji  file  aflects  them. 

Lastly,  Figure  5  indicates  Iiom*  a  .ou  file  is  made  from  an  ./or  .cl  file.  The  ou  file  is 
the  printed  output  that  would  result  if  the  ./  or  .cl  file  were  typed  into  sketch. 

4.  SPECIAL  TARGETS  USED  FOR  MAINTAINING  CODE.  Table  2  lists 


FIGURE  5:  MAKING  .ou  FILES 
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TABLE  2:  PART  1 

SPECIAL  TARGETS 

USED  FOR  MAINTAINING  CODE 

all 

Make.ti  all  code  larget-  files,  or  more  explicitly,  makes 
%ALL_FILES)  which  defaults  to  ''%(LHFILES)  %(OFILES) 
%(FILES)  %(OTHER  TARGET FILES}''. 

all.lhiiles 

Makes  all  .///  files,  or  more  explicitly,  HLHFILES). 

clean 

Removes  all  code  target  files,  and  also  all  documentation  tar¬ 
gets  and  other  miscellaneous  non-source  files.  More  explicitly, 
removes  %(ALUFILES)  WC  COUNT  *.€x  *.lli  *.o  *.lr  *.nl 

*.vs  *.in  *.$p  *.he  *.ori  and 

ex.clean 

Ih. clean 
o. clean 
s. clean 
nt.clean 
ou. clean 

Removes  only  e.r  files,  or  only  Ah  files,  etc. 

compile 

Makes  %lPREFIX)_compile.Oy  which  contains  all  of  this  pack¬ 
age  that  is  to  be  added  to  the  %{LISZT)  compiler  environment. 

count 

COUNT 

Makes  the  COUNT  file,  which  gives  a  line  count  breakdown  of 
all  V,SOURCE FILES),  for  both  code  and  documentation. 

demo 

Makes  all  %{DEMO^OUFILES)  .ou  files.  First  makes  the  same 
files  made  by  a//,  and  also  all  the 

$(  0  THER DEMO  TARGETJ^ILES). 

lint 

Makes  a  .nt  file  for  each  x  and  Ac  file  (more  explicitly,  for  each 
file  in  %{CFILES)  and  ^LCFILES)).  Makes  all  ^LHFILES) 
files  first. 

$(PREFIX)_lisp 

Makes  the  %(PREFIX)_lisp  file,  which  is  the  i{LJSP)  evaluator 
environment  with  this  package  added.  First  makes 
%{0F1LES),  then  loads  %(PREFIX)^load.o  into  t{LISP),  and 
lastly  dtimplisp's  the  result  into  %(PREFIX}_lisp. 
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TABLE  2:  PART  2 

SPECIAL  TARGETS 

USED  FOR  MAINTAINING  CODE 

#liap 

Makes  the  file  by  exactly  the  same  procedure  as  the 

%(PREFIX)lisp  file  is  made. 

list 

Outputs  all  the  names  of  the  files  in  %{LIST^ILES),  which 
by  default  equals  %{SOURCEJ'ILES).  Each  name  is  on  a 
separate  line. 

$(PREFrX)_liszt 

Makes  the  %(PREFIX)_liszl  file,  which  is  the  ^LlSZ'f)  com¬ 
piler  environment  with  this  package  added.  First  makes 
%{OFILES),  then  loads  %(PREFIX)Joad.o  into  ^LISZT), 
and  lastly  dumplisp’s  the  result  into  %(PREFIX)lisz(. 

^liszt 

Makes  the  ^liszt  file  by  exactly  the  same  procedure  as  the 
%(PREFIX}^liszt  file  is  made. 

load 

Makes  %(PREFIX)^load.o,  which  contains  all  of  this  pack¬ 
age  that  is  to  be  added  to  the  i{LISP)  evaluator  environ¬ 
ment. 

print 

Prints  all  the  code  source  files.  Specifically  prints 
%(LFILES)  %(CLFILES)  %(HFILES)  %'(CFILES) 

%(LCFILES)  %(CSFILES)  %(F  FILES)  %(MKFILES) 
%(SHFILES)  %(RCFILES)  and  %(OTHER_PRINT_FILES), 
the  last  of  which  defaults  to  %{OTHER_SOURCEJ'ILES). 
Also  makes  and  prints  the  WC  file,  which  lists  all  the  files 
printed  and  their  line,  word,  and  character  counts.  Files 
are  printed  in  alphabetical  order  of  their  name,  except  that 
the  WC  file  is  printed  first. 

print_with_count 

Just  like  print,  but  makes  and  prints  the  COUNT  file  in¬ 
stead  of  the  WC  file.  The  COUNT  file  is  more  meaningful, 
but  takes  longer  to  make  than  WC. 

rclcasc so  u  rce 

Releases  all  source  files  using  releaseillips). 

wc 

Makes  the  WC  file,  which  gives  the  line  count,  word  count. 

WC 

and  byte  count  of  the  files  printed  by  print. 

some  special  targets  used  for  maintaining  code. 

5.  DOCUMENTATION  FILE  EXTENSIONS.  Figure  6  indicates  the  file  exten- 
sions  and  make  paths  involved  in  making  documentation  targets.  Each  package  typically 
has  one  .ma  manual  file  which  is  successively  made  into  .tr,  .vs,  and  .vo  files  to  print  the 
package  manual.  In  the  first  step  the  glossary,  extracted  from  all  the  package 
%( GLOSS  ARY J'lLES)  (which  includes  all  source  files  except  .ma  and  .do  files),  is 
appended  to  the  end  of  the  .ma  file  to  make  the  .it  file:  see  sma^manual.sh  in  the 
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MANUALS  Appendix.  Also,  the  chapter  title,  as  defined  by  the  make  ^(CHAPTER)  and 
%(TITLE)  macros,  is  prepended  to  the  .via  file  in  this  first  step. 

The  .VO  files  actually  do  not  exist:  making  them  merely  causes  the  .i;5  files  to  be 
printed.  Such  non-existent  target  files  are  called  pseudofiles. 

Instead  of  making  .v$  and  .vo  files,  one  can  make  .ns  and  .no  files.  The  difference  is 
that  the  former  use  ditroff{\)  for  phototypesetter  like  printers,  and  the  later  use  nroj^l) 
for  typewriter  like  printers. 

Also  one  can  make  .he  and  .ho  files  instead  using  nro^l).  The  .he  files  are  like  .ns 
output  files,  but  contain  only  the  glossary,  and  have  specially  formatted  section 
headers  that  can  be  extracted  by  computer  programs.  They  are  designed  for  use  by  the 
on-line  help  facility  (which  is  not  yet  implemented).  The  .ho  pseudofile  is  used  to  print 
the  .he  file,  but  the  only  reason  for  doing  this  is  to  check  that  the  file  formating  is  OK  (in 
particular,  are  some  lines  too  long). 

Lastly,  one  can  also  make  .sp  files  made  by  running  the  .tr  file  derived  from  the  .ma 
file  through  the  spell(\)  program  to  produce  a  list  of  potentially  misspelled  words. 

Besides  .via  files  packages  may  have  miscellaneous  documents  represented  by  .do 
files.  These  can  be  printed  by  the  same  mechanisms  as  .ma  files,  with  the  difference  that 
no  chapter  title  or  glossary  is  added,  and  no  .he  files  may  be  made.  Figure  7  depicts  this. 


ditroff  '—me  '—t 


^^manuaish  ^^fCHAPTER)"  "^fTITLEf 

<file>.mG  %(GLOSSARYJ^ILES) 
I  pic  I  eqn  \  tbl 

spell  I  pr  —5  —11  —w80  —i 


FIGURE  6:  FILES  MADE  FROM  -ma  FILES 
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FIGURE  7:  FILES  MADE  FROM  .do  FILES 
6.  SPECIAL  TARGETS  FOR  MAINTAINING  DOCUMENTATION. 
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TABLE  3 

SPECIAL  TARGETS 

USED  FOR  MAINTAINING  DOCUMENTAION 

chap 

Makes  ${P/?£'F/A’)_chap.vo  which  prints  the  package  documenta¬ 
tion  chapter  or  appendix. 

chap  .vs 

Makes  the  $(P/?£'F/A')_chap.vs  file  which  is  the  trof[l)  output  file 
format  of  the  package  documentation  chapter  or  appendix.  Mak¬ 
ing  this  file  takes  a  lot  of  computer  time,  but  printing  is  takes  lit¬ 
tle.  so  often  this  file  is  made  in  background  and  then  printed  later. 

help 

Makes  the  $(P/?£'f’/A%chap.he  file  which  is  the  package  documen¬ 
tation  chapter  or  appendix  glossary  in  a  format  suitable  for  use  by 
the  on-line  help  command. 

lists  some  special  targets  used  for  maintaining  documention. 

7.  THE  TEAM  PROGRAMMER  SYSTEM.  The  Team  Programmer  System 
(TPS)  is  a  set  of  program  development  utility  programs  that  are  distributed  with 
SKETCH  and  used  by  SKETCH.  Here  we  briefly  describe  the  TPS  programs  used  by 
SKETCH  in  an  essentual  way. 

TPS  has  commands  to  search  the  directories  in  the  PATH  environment  variable  for 
a  file.  The  /search  program  is  used  to  find  the  complete  name  of  a  file  (or  each  of  a  list  of 
files)  by  searching  the  list  of  directories  given  by  PATH  for  the  file.  E.g.,  if 

PATH=.:/sketch/sketch4b/ll/sun3.5 

then 

/search  -rx  smk/smk_make.sh  sma/sma_index.sh 
might  return  the  line 

/sketch/sketch4b/ll/sun3.5/smk/smk_make.sh  \ 

/sketch/sketch4b/ll/sun3.5/sma/sma^ndex.sh 

The  options  — rwx  may  be  used  to  require  files  to  have  read,  write,  or  execute  privileges  to 
be  included  in  the  search. 

The  psearch  command  does  an  /search  like  action  on  its  first  argument,  and  then 
calls  that  first  argument  as  a  UNIX  program,  passing  the  rest  of  the  psearch  arguments 
to  that  program.  Thus  one  might  execute 

psearch  smk/smk_make.sh  chap 

Now  if  there  were  no  slash  (/)  in  the  name  of  the  command,  the  UNIX  shell  would  do  the 
same  thing.  Unfortunately,  the  shell  does  not  search  the  PATH  directories  if  there  is  a 
slash  anywhere  in  the  command  name  (not  just  at  the  beginning).  So  psearch  is  necessary 
when  there  is  a  slash  in  the  middle  of  the  command  name. 
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TPS  also  has  commands  to  install  files  in  public  locations.  The  key  program  is  the 
backup  program,  used  as  in 

backup  — D/sketch/sketch-4b/ll/sun3.5/sar  sar^defs.h  sarjoad.o 

This  program  takes  files  (sar^defs.h  and  sar^load.o)  in  the  current  directory  and  makes 
copies  in  another  directory  (/sketch/sketch‘4b/ll/sun3.5/sar)  which  holds  the  publically 
accessible  versions  of  these  files.  The  program  also  makes  backups  in  the  public  directory 
of  any  previous  public  versions  of  these  files  (see  the  TPS  documentation  for  details). 
Lastly,  the  backup  program  is  intelligent  in  two  ways.  First,  if  a  public  version  of  a  file 
already  exists  and  equals  the  current  directory  version  of  the  file,  then  the  program  does 
nothing,  neither  making  a  copy  of  the  files  or  making  backups.  Second,  if  a  copy  is  to  be 
made  of  a  read-only  file,  and  the  current  and  public  directory  are  on  the  same  file  system, 
no  copy  is  actually  made,  but  instead  the  public  version  of  the  file  is  linked  to  the  current 
directory  version.  This  saves  disk  space,  and  is  the  reason  that  the  SKETCH  make  facil¬ 
ity  makes  all  target  files  read-only. 

A  companion  to  the  backup  program  is  the  release  program,  used  as  in 
release  — D/sketch/sketch4b/ll/sun3.5/sar  sar_defs.h  sarjoad.o 

This  program  merely  destroys  all  backups  of  the  indicated  files  that  are  in  the  public 
directory  (not  backups  in  the  current  directory).  It  also  makes  the  public  directory  ver¬ 
sions  of  the  files  read-only  (if  they  are  not  already  such). 

The  backup  and  release  programs  can  be  used  without  the  —D  option  to  backup  and 
release  files  in  the  current  directory.  The  backups  are  made  in  the  current  directory. 
However,  linking  of  read-only  files  is  never  done,  and  instead  backup  always  make  a  new 
copy  of  the  file  being  backed  up  that  is  owned  and  writable  by  the  person  running  the 
backup  program,  so  that  that  person  can  edit  the  file. 

More  details  about  TPS  programs  are  contained  in  the  TPS  documentation. 

8-  INSTALLING  PUBLIC  VERSIONS. 

9.  GLOBAL  DIRECTORIES.  A  global  directory  is  a  directory  that  contains  pack¬ 
age  subdirectories.  For  example,  a  global  directory  might  contain  subdirectories  named 
smk  and  sma  for  the  MAKING  FILES  and  WRITING  MANUALS  packages,  respectively. 

A  global  directory  should  contain  three  files:  cs/i.rc,  sketchsCf  and  sketchcom.rc. 
These  files  establish  environment  for  the  make,  sketch,  and  sketchcom  programs,  respec¬ 
tively. 

These  .rc  files  establish  a  sequence  of  global  directories  recorded  in  various  directory 
search  paths.  If  a  file  is  not  found  in  the  current  global  directory,  then  the  next  global 
directory  in  the  path  is  searched,  and  so  forth.  For  example,  csk,rc  might  be 

set  path=(.  /ul/walton/sketch4/users  /sketch/sketch4b/ll/sun3.5  \ 

/sketch/sketch4b/ll/sun3.5/tps  /usr/local/bin  /usr/ucb  /usr/bin  /bin) 

rehash 

setenv  CPP^PATH  I/ul/walton/sketch4/users  “I/sketch/sketch4b/ll/sun3.5” 

if  the  global  directory  were  /ul/walton/sketch4/users.  If  a  file  is  not  in  this  directory, 
then  /sketch/sketch4b/ll/sun3.5  is  searched. 

Suppose  the  /sketch/sketch4b/ll/sun3.5  directory  contains  an  sed  package  subdirec¬ 
tory.  If  a  copy  of  this  subdirectory  were  made  in  /ul/walton/sketch4/users  and 
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modified,  then  all  jobs  run  within  the  /ul  \valton/sketch4/users  directory  and  its  sul> 
directories  would  use  the  modified  sed  package,  while  all  jobs  within 
/sketch/sketch^b  11  sun3.5  and  its  subdirectories  would  use  the  original  sed  package. 

Thus  it  is  pos.sible  to  build  a  tree  of  different  versions  of  SKETCH. 

The  PATH  environment  variable  (which  is  set  from  the  path  csli  variable)  not 

only  lists  the  global  directory  sequence,  but  also  lists  other  places  to  obtain  program  files, 
such  as  for  tlie  current  directory  and  /sketch/sketch4b/ll/sun3.5/tps  for  the  TPS  pro¬ 
grams  (see  THE  TEAM  PROGRAMMER  SYSTEM  above). 

A  typical  sketch. rc  file  is 
(setq  lisp-library-directory 

(tilde-expand  '  /sketch/skcich4b/ll/siin3.6/lisp/lisplib)) 

(sstatus  data-search-path  (|.|  /msmil/data4  /sketch/sketch4b/ll/sun3.5)) 

(sstatus  catalog-search-path  (|. |  /'msmil/exper4  /sketch/sketch4b/ll/sun3.5)) 
(sstatus  cache-search-path  (|.|  /msmil/data4  /sketch/sketcli4b/ll/sun3.5)) 

(sstatus  foni-search-path  (|.|  /skei.ch/sketch4b/ll/sun3.5/vfonts 

/sketch/sketch4b/ll/sun3. 5/fonts)) 

(sstatus  load-search-path  (|.I  /msmil  /exper4  /ul/walton/sketch4/users 

-'.sketch  /sketch4b/ll/sun3.5 

/sketch  .sketch4b/ll/sun3.5/lisp/lisplib)) 

(load  ’display. rc) 

Here  /msmil/e.\pcr4  is  a  global  directory  in  which  experiment  jobs,  in  the  form  of  inter¬ 
preted  LISP  programs,  are  placed,  and  /msmil/data4  is  a  global  directory  holding  binary 
data  files;  e.g.  arrays.  Files  in  all  these  global  directories  must  be  referenced  by  giving  a 
package  subdirectory  name,  which  serves  to  identify  the  directory  that  contains  the  file 
and  makes  the  order  in  which  global  directories  are  listed  in  sketch. rc  unimportant  (unless 
a  package  in  one  global  directory  has  the  same  subdirectory  name  as  a  package  in 
another).  Thus  a  data  file  might  be  referred  to  as  exl/jul8l/t..l.ar  which  would  be  inside 
the  jul8l  dataset  in  the  exl  package  subdirectory  of  one  of  the  various  global  directories 
(/msmil/data4  probably). 

The  display. rc  file  mentioned  at  the  end  of  sketch. rc  initializes  the  display  system: 
see  the  DISPLAY  chapter. 

Sketchcom.rc  is  usually  symbolically  linked  (by  In  -5)  to  sketch.rc^  so  that  the  com¬ 
piler  sees  the  same  initializing  file  as  the  evaluator. 

A  global  directory  has  a  makefile. mk  file  which  can  contain  most  of  the  same  macros 
as  a  package  directory  makefile. mk:  see  Table  1.  Macros  that  are  not  used  in  a  global 
directory  are  CHAPTER,  PREFIX,  PACKAGEJ)IRECTORY,  and  TITLE.  Instead  or 
these,  the  macros  of  Table  5  may  be  defined  in  a  global  directory. 

10.  TARGETS  IN  GLOBAL  DIRECTORIES.  Making  a  target  in  a  global  direc¬ 
tory  is  like  making  a  target  in  a  package  directory,  except  that  targets  that  make  files 
whose  name  includes  %{PREFIX)  or  %{PACKAGeLdIRECTORY)  cannot  generally  be 
made  in  the  global  directory.  However,  the  following  targets  work  in  the  global  direc¬ 
tory— 
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TABLE  5 

GLOBAL  DIRECTORY  DEFINING  MACROS 

Macro  Name 
’’Default  Value” 

Definition 

INDEXLAJPPENDDC 

The  appendix  letter  of  the  index  of  all  the  packages  in 
^(PACKAGES)  which  is  built  by  the 

qlobaLindex.  <xx>  targets. 

INDEX_TITLE 

The  title  of  the  index  of  all  packages  in  ^(PACKAGES) 
which  is  built  by  the  global indeT.  < xx>  targets. 

LINK_DIRECTORY 

"<  iUegal_valve>" 

The  global  directory  into  which  %(LIj\’I\^FILES)  are 
linked  by  the  link  make  target.  This  can  be  defined  for 
package  directories  too,  but  generally  is  not. 

PACKAGES 

tff  tt 

The  list  of  package  subdirectories  that  are  to  be  pro¬ 
cessed  by  the  <\\\> .packages  targets  of  this  global 
directory.  These  subdirectories  need  not  be  in  the  glo¬ 
bal  directory  itself  as  long  as  they  are  in  the  path  of 
global  directories. 

clean^install 

backup^install 

relcase^install 


With 

^  INSTA  LL_DIRECTOR)y${PA  CKA  GE_DIR  ECTOR ) ) 
replaced  by  ^INSTALLJ)IRECTOR\), 


Making  a  target  named  < target in  the  global  directory  makes  <tar- 
get>  in  each  package  subdirectory  listed  in  %{PACRAGES)^  for  each  package  <target> 
whose  name  does  not  include  a  package  %{PREFIX). 

The  following  <target>.pacA:aye5  targets  pass  the  indicated  make  macro  values  to 
the  package  make  commands  when  they  execute— 


backup^install.  packages 
release^ins  tall,  packages 
clean_install. packages 
list. packages 
link. packages 


\NSTALLJ)\RECTORY=${INSTALLJ)IRECTOR  Y) 
\NSTALLJ)\REaTORY=^INSTALL_DIRECTORY) 
\NSTALLJ)lRECrrORY^%{INSTALL_DIRECTOR  Y) 
LIST J'ILES=$(F>i  CKA  GEJ.ISTJ^ILES) 
LINIC-FILES=^Fyi  CKA  GEJ.INKJ^ILES) 
LINICJ)IRECTORY= 

%{LINKJDIRECTOR  Y)/<  package-directory  > 


Actually,  the  directory  names  are  converted  to  non-relative  form  before  they  are  passed. 
The  < package-directory >  refers  to  the  element  of  the  ^{PACKAGES)  macro  value. 

Sometimes  it  is  desirable  for  demo. packages  to  pass  the  i{DEMO^ISP)  and 
^DEMO^ISZT)  values  to  the  package  make,  so  there  is  a  variant  named 
global. demo. packages  that  does  this  by  passing- 
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DEMO_LISP=$(  Z)£MO_I/SP) 
DEMO_L\SZT=^DEMO^ISZT) 

When  defining  %{PACKAGE_LIST_FILES)  and  %{PACKAGE_LINK_FILES) 
must  double  the  dollar  signs.  For  example- 


one 


make  ' PAGKAGE^IST_FILES=%%{HFILESf  list.packages 


TABLE  6 

SPECIAL  TARGETS 

USED  IN  GLOBAL  DIRECTORIES 

global_count 

GLOBAL.COUNT 

Makes  tlie  file  GLOBAL^COUNT  by  combining  the 
COUNT  file  and  all  the  < package >/<70f/N7’  files  for 
every  <package>  in  %(PACKAGES). 

You  must  make  couni.packages  first:  it  is  not  done  au¬ 
tomatically. 

global.demo. packages 

Like  global.packagts,  but  passes  the  global  directory 
definition  of  %(DEMOJ.ISP)  and  %(DEMOMSZT)  to 
the  packages  to  produce  the  demo  .ou  files.  This  is 
used  in  public  global  directories  where  the  binary  files 
required  to  use  the  package  defintions  of 
%(DEMOMSP)  and  %(DEMOJ.ISZT)  are  not  avail¬ 
able. 

glob  aLindex.tr 
glob  aLin  d  ex  .vs 
globaLindex.vo 

Makes  the  file  globaLtndcx.tr  by  combining  all  the  in¬ 
dex  files  <package>/<prefix>_chap.in  for  every 
<package>  in  ^(PACKAGES).  Other  documentation 
target  files  are  made  from  globaLindcxAr  in  the  usual 
ways. 

You  must  make  indcx.packagcs  first:  it  is  not  done  au¬ 
tomatically. 

manual 

Prints  the  entire  manual  by  making  the  following  in 
order:  title,  vo,  indcx.packagcs,  globaLindex.vo, 

chap. packages. 
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Table  6  gives  some  other  special  targets  that  can  be  used  in  global  directories  only. 

11.  DEFINING  UNIX  PROGRAMS.  The  UNIX  programs  invoked  by  make  and 
the  flags  passed  to  these  programs  are  mostly  defined  by  macros.  Thus  they  can  be 
replaced  and  modified  by  redefining  their  macros  in  the  makefile. ink. 

For  example,  every  time  a  LISP  evaluator  environment  is  needed,  SKETCH  make 
uses  $(L/S'P),  which  is  usually  defined  by  the  default  definitions— 

LISP=$(SKETCH) 

SKETCH^ketch 

If  we  put  — 

LISP=lisp 

into  makefile. mkj  we  would  get  the  lisp{\)  program  instead,  whenever  a  LISP  evaluator 
environment  was  needed  by  make. 

The  LISP  evaluator  environment,  $(L/5P),  and  the  LISP  compiler  environment, 
%(LISZT),  are  the  programs  most  commonly  redefined  in  makefile. mk.  The  default 
definitions  of  various  programs  are  in  the  $co_defsl.mk  file  of  the  sco  (configuration) 
package,  and  may  need  to  be  changed  when  SKETCH  is  ported  to  a  new  computer. 

Program  flags  are  defined  by  macros  separate  from  the  program.  Usually  a  program 
like  %{LISZT)  will  have  a  related  set  of  flags  named  by  appending  ''J'LAGS*  to  the  pro¬ 
gram  macro  name.  Thus  %LISZT^FLAGS),  which  defaults  to  to  suppress  verbose 
output  from  the  LISP  compiler. 

Macro  definitions  may  be  overridden  by  providing  new  definitions  as  arguments  to 
the  make  UNIX  command.  For  example, 

make  lISZTJ^LAGS-=^  ... 

will  make  target  files  with  liszt  flags  defined  to  be  the  null  string,  thus  causing  verbose 
liszt  compiler  output. 

Not  all  program  flags  are  controlled  by  this  mechanism.  For  example  the  -5  flag  to 
cc  that  makes  a  .s  file  from  a  .c  file  is  not:  it  is  controlled  by  the  kind  of  file  being  made. 

Table  7  lists  the  program  and  flag  macros  most  commonly  used  while  making  target 
program  code  files.  — Z)  flags  for  the  C  macro  preprocessor  are  put  into  ^{GPPJ'LAGS}, 
while  libraries  to  be  searched  by  the  loader  are  put  into  ^{LIBRARIES}. 

There  are  a  very  large  number  of  UNIX  program  macros  not  in  Tabic  7:  see  the 
glossary  for  the  program  you  want  to  modify. 

12.  HITLIST. 

(1)  Finish  tutorial  documenation. 

(2)  Check  to  be  sure  make  index  makes  global  index  before  local  indexes:  there  may  be  a 
bug  here?  it  may  also  ignore  existing  index. vs? 

(3)  Be  sure  all  global  directory  targets  are  documented. 

(4)  Be  sure  count  and  index  can  be  made  from  global  install  directory. 

(5)  Make  global  #lisp  and  #liszt  (via  environments,  whatever  that  means?). 
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TABLE  7:  PART  1 

PROGRAM  AND  FLAG  MACROS 

Program 

Flags 

Macro 

Macro 

Use 

"default" 

"default" 

${AS) 

It  ft 

as 

$(AS_FLAGS) 

ttit 

Assemble  .s  files  to  make  .0  files. 

^CC) 

$(CC_FLAGS) 

C  Compiler.  The  flags  are 

tt  tt 

CC 

"-0" 

separated  into  3  groups:  com¬ 
piler  proper  (cc),  macro  prepro¬ 

${CPP_FLAGS) 

cessor  (cpp),  and  loader  (Id). 
^LIBRARIES}  is  like 

^LD_FLAGS),  but  placed  after 

$(LD_FLAGS) 

the  list  of  file  names  passed  to 

lift 

the  loader,  instead  of  before  that 
list. 

${LIBRARIES) 

lift 

${LINT) 

$(LINT_FLAGS) 

Lint.  The  flags  are  separated 

"psearch 

into  2  groups:  lint  proper  (lint) 

sink /s  7yik_ii7if.$h** 

${CPP_FLAGS) 

tttt 

and  the  macro  preprocessor 
(cpp).  %{LINTJ^LAGS}  and 
%{LINT^IBRARIES)  are  both 
passed  to  lint  proper,  but  the 

${LINT_LIBRARIES) 

first  goes  at  the  beginning  of  the 

"^(LIBRARIES)" 

argument  list  and  the  second 
goes  at  the  end.  Smk/lini.sh  is  a 
special  version  of  Uni  that  gets 
rid  of  certain  meaningless  warn¬ 

ing  messages. 
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TABLE  7:  PART  2 

PROGRAM  AND  FLAG  MACROS 

Program 

Macro 

"default" 

Flags 

Macro 

"default" 

Use 

$(LISP) 

"%(SKETCHr 

$(LISP_FLAGS) 

Lisp  evaluator  environment. 

$(DEMOJ.ISP) 

"%(LISP) 

-/  %(PREFIX)Joad' 

Lisp  evaluator  environment 
used  to  make  .ov  files  from 
.1  files  via  the  demo  func¬ 
tion. 

?;(LISZTJ 

"tISKETCHCOM)" 

$(LISZT_FLAGS) 

ft  ft 

-<7 

Lisp  compiler  environment. 

$(DEMO_LISZT) 

''%(LISZT) 

-/  %(PREFlX)_compUe" 

Liszt  compiler  environment 
used  to  make  .ou  files  from 
.cl  files  via  the  demo  func¬ 
tion. 

$(SKETCH) 

"sketch" 

SKETCH  evaluator  environ¬ 
ment. 

$(SKETCHCOM) 

"sketchcom" 

SKETCH  compiler  environ¬ 
ment. 

(6)  Explain  environment  use.  Make  them  use  .o  files.  Explain  declare  (macros  t). 
Explain  need  to  def  macros  before  use. 

13.  GLOSSARY. 

all  (MAKE  Target] 

WHEN  MADE:  Makes  V^ALLJ'ILES). 

$(ALL_FILES)  [MAKE  Macro] 

VALUE:  A  list  of  all  the  package  files  that  must  be  made  from  other  files  (does  not 

include  intermediate  files  that  may  not  have  to  be  made).  Default  value: 

’'%{LHFILES)  %{OFILES)  ${F1LES)  %{OTHER_TARGET_FILES). 

WARNING:  These  files  are  all  removed  by  cleaning. 
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ail.lhfiles 

W^ENKIADE:  Makes; 
$(AS) 


[MAKE  Target] 


[MAKE  Macro] 


VALUE:  The  name  of  the  UNIX  flv<?(l)  program.  Usual  default:  "os". 

${AS_FLAGS)  [MAKE  Macro] 

VALUE:  The  flags  for  the  UNIX  as{l)  program.  Usual  default: 

${BACKUP)  [MAKE  Macro] 

VALUE:  The  name  of  the  TPS  bacfciip{tps)  program.  Usual  default:  "backup". 

${BACKUP_FLAGS)  [MAKE  Macro] 

VALUE:  The  flags  for  the  TPS  bnckup{tps)  program.  Usual  default: 

backup_install  [MAKE  Target] 

VALUE:  Installs  ${f.\STALL_FILES)  in 

${INSTALL_DIRECTOR  \')/%[PA  CKA  GEJDIRECTOR 
by  using  backup{{ps)  with  the  —D  and  —remove  options. 


In  the  global  directory,  %{lNSTALL_DIRECTOR'l')  is  used  in  place  of 
^INSTALL_DIRECTOR  'i')/%{PA  CKA  GEJDIRECTOR  Y). 


.c  [UNIX  File  Extension] 

FILE  FORMAT:  A  C  source  file.  Can  be  made  into  an  .ex,  .o,  .s,  or  .nt  file  (all 
%[LHFILES)  are  all  made  first). 


$(C2)  [MAKE  Macro] 

VALUE:  The  name  of  the  UNIX  C  compiler  optimizer  program.  Usual  default:  "/lib/cH'. 

•ca  [UNIX  File  Extension] 

FILE  FORMAT:  SKETCH  catalog  files.  See  CATALOGS  chapter. 
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$(CC)  [MAKE  Macro) 

VALUE:  The  name  of  the  UNIX  cc(l)  program.  Usual  default:  **cc\ 

$(CC_FLAGS)  [MAKE  Macro] 

VALUE:  The  flags  for  the  UNIX  cc(l)  program.  These  should  not  include  flags  for  the 

macro  preprocessor  cpp^  the  loader  and  which  are  separate. 

Default  value:  "-O’*. 

^CCOM)  [M\KE  Macro] 

VALUE:  The  name  of  the  UNIX  C  compiler  program.  Usual  default:  *yiib/ccom'\ 

$(CFILES)  [MAKE  Macro] 

VALUE:  A  list  of  all  the  c  files  in  the  package.  These  are  assumed  to  be  source  files. 
Default  value: 


chap  [MAKE  Target] 

WHEN  M\DE:  Makes  ${PREFIX)^cliap.vo. 

$(CHAPTER)  [MAKE  Macro) 

V.ALUE:  The  number  (1,  2,  3.  etc.)  of  the  package  chapter  or  the  letter  (A,  B,  C,  etc.)  of 
the  package  appendix. 


chap.vs  [MAKE  Target] 

WHEN  MADE:  Makes  ${PREFIX)^cliap.vs  and  ^PREF IX)^cliap.iiL 


,ci  [UNIX  File  Extension] 

FILE  FORMAT:  SKETCH  catalog  file  index.  See  has-tndcx-file  under  a^catalog  in  the 
CATALOGS  chapter. 


Can  be  made  from  a  xa  file.  The  procedure  to  do  this  invokes  make- 
catalog-index  in  ^{SKETCH).  In  order  for  this  to  work, 
${PAKCAGEU)IRECTOR)^  must  be  the  name  of  the  current  directory 
relative  to  one  of  the 


directories. 


[status  catalog-search-path) 
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•cl  [UNIX  File  Extension] 

FILE  FORNLAT:  A  LISZT  source  file.  Can  be  loaded  directly  into  LISZT  by  the  /oac/ func¬ 
tion,  or  made  into  a  .e^-or  .ou  file. 


The  only  proper  way  to  make  a  xl  file  into  a  .ex  file  is  directly,  without 
intervening  .$  or  .0  files,  in  which  case  the  .cl  file  is  loacPed  into  ${LISZT) 
and  the  result  duinplisp'ed  to  the  .ex  file. 


clean 
ex  .clean 
he.clean 
Ih. clean 
nt. clean 
ns.clean 
o. clean 
ou  .clean 
s. clean 
sp. clean 
tr. clean 
vs. clean 

WHEN  MADE: 


[MAKE  Target] 
[MAKE  Target] 
[MAKE  Target] 
[MAKE  Target] 
[MAKE  Target] 
[MAKE  Target] 
[MAKE  Target] 
[MAKE  Target] 
[MAKE  Target] 
[MAKE  Target] 
[MAKE  Target] 
[MAKE  Target] 

Cleaii  removes  all  non-source  files.  More  explicitely,  it  removes 
^ALL_FILES}  \VC  COUNT  *.ex  \lli  \o  \s  \lr  * .jit  *.ns  \vs  \in  \sp 
*  .he  *  .ou  and  . 


<\x>  .clean  removes  all  files  with  extension  ".<xx>'*. 


Clean  and  <x\>  .clean  are  defined  with  a  double  colon  ::  and  can  there¬ 
fore  be  added  to  by  defining  new  entries  such  as— 

clean:: 

rm  -f ... 


WARNING:  If  you  execute— 

make  clean  ...  Sc>make.ou  & 

you  will  remove  the  make.ou  file  before  you  can  look  at  it. 

clean^install  [MAKE  Target]  • 

VALUE:  Removes  the  directory 

%{INSTALLJ)IRECTOR  Y)/i{PA  CKA  GEJ)lRECTOR  Y) 

with  rm  — r/  and  remakes  it  with  mkdir.  Gives  the  directory  group  write  per¬ 
mission. 

In  the  global  directory,  %{INSTALL^IRECTORY)  is  used  in  place  of 
%{INSTALL^DIRECTOR  Y)/%{PA  CKA  GEJ)IRECTOR  Y), 

and  rm  — /  is  used  in  place  of  rm  --rj^  so  that  only  ordinary  files,  and  not  sub¬ 
directories,  are  removed. 
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Clean^mstall  is  defined  with  a  double  colon  ::  and  can  therefore  be  added  to  by 
defining  new  entries  such  as-“ 

cleoD^iiistall:: 

rm  -rf  ... 
mkdir  ... 
chmod  g-fw  ... 


$(CLFILES)  [MAKE  Macro] 

VALUE:  A  list  of  all  the  .cl  files  in  the  package.  These  are  assumed  to  be  source  files. 
Default  value: 

%{DE.\JO_CLFILES)  %{OTHER^CLFILES}'\ 


$(COL)  [MAKE  Macro] 

VALUE:  The  name  of  the  UNIX  col[\)  command  used  to  remove  reverse  line  feeds.  Usual 
default:  "coF. 

${COLUMNS)  [MAKE  Macro] 

VALUE:  The  name  of  the  UNIX  command  to  print  a  list  of  words  in  5  columns  on  a  ter¬ 
minal.  Usual  default:  *’pr  -5  -/i  ’w80  Used,  for  example,  to  output  spelling 
errors. 

$(COMMONJLFILES)  [MAKE  Macro] 

VALUE:  A  list  of  all  the  ./  files  in  the  package  that  are  included  in  both 
%{PREFIX)^load.l  and  %[PREFIX)^compile.l.  These  are  assumed  to  be  source 
files.  Default  value:  ”**. 


compile  [MAKE  Target] 

WHEN  MADE:  Makes  %{PREFIX)^compilc.o. 

${COMPILEJLFILES)  [MAKE  Macro] 

VALUE:  A  list  of  all  the  ./  files  in  the  package  that  are  included  in  %{PREFIX)^compUc.l 
but  not  %{PREFIX)^load.l.  These  are  assumed  to  be  source  files.  Default  value: 

till 
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${COMPUTER_TYPE)  [MAKE  Macro] 

$(COMPUTER^TYPE)  [UNIX  Environment  Variable] 

V.\LUE:  Tlie  type  of  the  computer,  either  sunS  or  vax,  on  which  SKETCH  is  running. 

Each  compute  type  has  its  own  set  of  SKETCH  directories,  but  these  may  share 
sources  in  a  common  directory:  see  the  link  make  target. 

Must  be  set  in  csh.rc  files.  %{COMPUTER^TYPE)  is  a  UNIX  Environment 
variable  turned  by  make  into  a  make  macro. 

$(COUNT)  [MAKE  Macro] 

VALUE:  The  name  of  the  line  counting  program.  Usual  default: 

psearch  sma/sma^couni.sh. 


count  [MAKE  Target] 

COUNT  [MAKE  Target] 

COUNT  [UNIX  File  Name] 

WHEN  NL-U)E:  ^(COlWTys  ^SOURCE^FILES)  and  puts  the  result  into  the  file  named 
COLWT 

$(COUNT_FLAGS)  [MAKE  Macro] 

VALUE:  The  Hags  for  the  line  counting  program.  Usual  default: 


$(CPP)  [MAKE  Macro] 

VALUE:  The  name  of  the  UNIX  cpp  C  macro  processor  program.  Usual  default: 
'yiib/cpp'. 

${CPP_FLAGS)  [MAKE  Macro) 

VALUE:  The  flags  for  the  UNIX  C  macro  preprocessor  cpp.  Default  value; 
"$(CPP_PATH)". 

${CPP_PATH)  [MAKE  Macro] 

${CPP_PATH)  [UNIX  Environment  Variable] 

VALUE:  An  argument  for  cc  of  the  form  "—/directory  Gives  the  directories  to  be 
searched  for  ./»  files. 


Must  be  set  in  csh.rc  files.  %{CPPJ*ATH)  is  a  UNIX  Environment  variable 
turned  by  make  into  a  make  macro. 
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.cs  [UNIX  File  Extension] 

FILE  FORMAT:  A  macro  assembly  language  source  file.  Can  be  made  into  a  .$,  .0  or  .ex 
file.  Is  made  into  a  .$  file  by  running  through  the  C  macro  preprocessor, 
but  not  the  rest  of  the  C  compiler. 

$(CSFILES)  [MAKE  Macro] 

VALUE:  A  list  of  all  the  .cs  files  in  the  package.  These  are  assumed  to  be  source  files. 
Default  value: 

csh.rc  (UNIX  File] 

VALUE:  A  file  in  the  global  directory  that  defines  the  directories  used  by  make.  It  should 
have  roughly  the  form- 

set  path=(<this-directory >  < next-directory >  ... 

<tps-directory  >  /usr /local/bin  /usr/ucb  /usr/bin  /bin) 

rehash 

setenv  CPP.PATH  **-I<this-directory >  -I < next-directory >  ...” 
setenv  INSTALL^DIRECTORY  <this-directory >/pub 
setenv  COMPUTER^TYPE  <computer_t> pe> 

where  the  chain  of  directories  to  be  searched  for  SKETCH  program  and  data 
files  is  < this-directory >  < next-directory >  ...,  and  the  directory  in  which  the 
public  versions  of  these  files  are  to  be  installed  is  usually  named  pub  relative  to 
this  directory  (but  a  relative  name  cannot  be  used  in  csh.rc).  The 
<computer_type>  is  typically  either  sun3  or  vax. 

demo  [MAKE  Target] 

VALUE:  Makes  ${DEMO.OUFILES). 

${DEMO«CLFILES)  [MAI^  Macro] 

VALUE:  A  list  of  all  the  .cl  files  in  the  package  that  are  demonstrations  which  can  be 

loaded  into  %{PREFIX)^liszt  by  the  demo  function.  These  are  assumed  to  be 
source  files.  Default  value: 

${DEMO  J.FILES)  (MAKE  Macro] 

VALUE:  A  list  of  all  the  .1  files  in  the  package  that  are  demonstrations  which  can  be 

loaded  into  %{PREFIX)^lisp  by  the  demo  function.  These  are  assumed  to  be 
source  files.  Default  value: 
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$(DEMO_LISP)  [MAKE  Macro] 

V.-U.UE:  The  name  of  the  LISP  evaluator  program  used  to  make  .ou  files  from  ./  files. 
Usual  default: 

"$(L/SF)  -I  %(PACKAGE_DIRECTOR\')/%{PREFIX)Joad' 
in  package  directories,  and  just  ''%{LISP)''  in  global  directories. 

${DEMO_LISZT)  [MAKE  Macro] 

VALUE:  The  name  of  the  LISZT  evaluator  program  used  to  make  .ou  files  from  .cl  files. 
Usual  default: 

''%[LISZT)  -I  %{PACK.\GEJ)IRECTORY)/%{PREFIX)_compile' 
in  package  directories,  and  just  "%[LISZT)"  in  global  directories. 

${DEMO_OUFILES)  [MAKE  Macro] 

VALUE:  A  list  of  all  the  .ou  files  that  can  be  made  from  demo  ./  files.  These  files  are 

made  by  the  "make  demo".  Default  value: 

$(DEMO_TARGET_FILES)  [MAKE  Macro] 

VALUE:  A  list  of  all  the  files  that  should  be  made  before  making  any  file  listed  in 
${DEMO_OUFILES).  Default  value: 

"${ALL_FILES}  $(  O THER_DEMO_ TARGET_FILES)" 

However,  demo. packages  (but  not  local. demo. packages)  explicitly  sets  this  to 
equal— 

"${OTHER_DEMO_  TARGE  T^FILES)" 


${DITROFF)  [MAKE  Macro] 

VALUE:  The  name  of  the  UNIX  trofl[\)  program.  Usual  default:  "ditroff  -me".  Use  the 
value  "iroff  -me  -rvl"  with  an  IMAGEN  printer. 

${DITROFF_FLAGS)  •'  [MAKE  Macro] 

VALUE:  The  flags  for  the  UNIX  trofl[\)  program.  Usual  default: 

.do  [UNIX  File  Extension] 

FILE  FORMAT:  A  document  source  file.  Can  be  made  into  a  .tr,  .sp,  .vs,  .vo,  .ns,  or  .no 
file.  Is  made  into  a  .tr  file  by  passing  through  p«c(l),  C9n(l),  and 


Printed  May  1,  1989 


MAKING  FILES 


C-33 


${DOFILES)  [MAKE  Macro] 

VALUE:  A  list  of  all  the  .do  files  in  the  package.  These  are  assumed  to  be  source  files. 
Default  value: 


${EQN)  [MAKE  Macro) 

VALUE:  The  name  of  the  UNIX  C77j(1)  program.  Usual  default:  ''eq7i\ 

WARNING:  Do  not  use  eqn  constructs  in  files  to  be  nroff  ed. 

$(EQN^FLAGS)  [MAKE  Macro] 

VALUE:  The  flags  for  the  UNIX  eqii{l)  program.  Usual  default:  ****. 


.ex  [UNIX  File  Extension] 

FILE  FORMAT:  An  executable  program  file.  Usually  such  files  named  xxx.ex  are  linked 
into  file  names  xxx  before  they  are  used,  but  since  inahe  does  not  handle 
files  with  no  extension  automatically,  it  is  not  possible  to  drop  the  .ex 
extension  completely.  Rather,  the  xxx.ej  file  is  made  as  an  intermediate 
step,  and  the  xxx  file  is  made  from  it  by  including  in  makefile. luk  the 
lines- 


xxx:  xxx.e.r 

rm  T  xxx 
In  xxx.ej  xxx 

Can  be  made  from  ./,  .cl,  .c,  .cs,  .s,  or  .0  files 


.f  [UNIX  File  Extension] 

FILE  FORMAT:  A  FORTRAN  source  file.  Can  be  made  into  a  ,€x,  .0,  or  .s  file. 

WARNING:  FORTRAN  source  files  are  not  yet  implemented. 

${FFILES)  [MAKE  Macro] 

VALUE:  A  list  of  all  the  ./  files  in  the  package.  These  are  assumed  to  be  source  files. 
Default  value: 

$(FILES)  [MAKE  Macro] 

VALUE:  A  list  of  all  the  package  files  that  have  no  extension  and  that  must  be  made 
from  other  files.  These  files  are  made  by  ''make  air.  Default  value: 

WARNING:  These  files  are  all  removed  by  cleaning. 
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global_count  [MAKE  Target] 

GLOBAL.COUNT  [MAICE  Target] 

WHEN  MADE:  Makes  the  file  GLOBAL_COUNT  by  combining  the  COUNT  file  and  all 
the  <package>/CO[/NJ  files  for  every  <package>  in  ^{PACKAGES). 
This  combination  is  done  by  the  %{COUNT)  program. 

These  make  targets  can  only  be  made  in  a  global  directory. 


global_index.tr 

global_index.vs 

global_index.vo 

$(INDEXLAPPENDIX) 

${INDEX:.TITLE) 


[MAKE  Target] 
[MAKE  Target] 
[MAKE  Target] 
[MAKE  Macro] 
[MAKE  Macro] 


WTO;n  MADE:  These  make  global_index.lr,  globaLindex.vs,  and  global_index.vo  where 
globaUindex.tr  is  made  by  running  the  %{INDEX)  program  against  the 
<package_directory >/<prefix>_chap.in  files  for  each  package  prefix 
listed  in  %{PACKAGE^. 


^INDEX_APPENDIX)  becomes  the  index  appendix  letter,  while 
^INDEX_TITLE)  becomes  the  index  appendix  title.  These  default  to  "A” 
and  "INDEX"  respectively. 


These  make  targets  can  only  be  made  in  a  global  directory. 

${GLOSSARY_FILES)  [MAKE  Macro] 

VALUE:  .A  list  of  all  the  source  files  in  the  package  that  may  contain  glossary  entries. 
Default  value:  "${PRINT_FILES)''. 


•h  [UNIX  File  Extension] 

FILE  FORMAT:  A  C  source  file  containing  definitions  included  in  various  other  C  files  by 
means  of  the  C  preprocessor  #mc/udc  statement. 


.he  [UNIX  File  Extension] 

FILE  FORMAT:  Help  file.  Can  be  displayed  on  the  screen.  Can  be  made  from  a  .ma  or  .tr 
file. 
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help  [MAKE  Target] 

WHEN  MADE:  Makes  ^PREFIXUcllap.he. 

$(HEJPRINT)  [MAKE  Macro] 

VALUE:  The  name  of  the  UNIX  program  that  prints  .he  files.  Should  handle  underlining. 
Usual  default:  "priiif.  Use  the  value  "jrnprin/**  with  an  IMAGEN  printer. 

$(HEJPRINT_FLAGS)  (MAKE  Macro) 

VALUE:  The  flags  for  the  UNIX  %{HE^PRINT)  program.  Usual  default: 

$(HFILES )  [MAKE  Macro) 

VALUE:  A  list  of  all  the  .h  files  in  the  package.  These  are  assumed  to  be  source  files. 

Default  value: 


.ho  [UNIX  File  Extension) 

FILE  FORMAT:  A  fictitious  file  which  when  made  causes  the  corresponding  .he  file  to  be 
printed.  Can  be  made  from  a  .ma,  ./r,  or  .he  file. 


.in  (UNIX  File  Extension] 

FILEFORM'\T:  A  %{MANUAL)  index  file.  Made  as  a  side  effect  of  making  a  ,ma,  .do,  or 
.tr  file  into  a  .vs  or  .vo  file. 


Because  of  the  way  this  file  is  made  it  currently  contains  not  only  index 
entries,  but  also  all  error  messages  from  the  troff  job  that  made  it.  These 
are  extracted  so  the  user  can  see  them  by  the  make  job  that  runs  troff. 

$(INDEX)  [MAKE  Macro) 

VALUE:  The  name  of  the  SKETCH  index  program.  Usual  default: 

psearch  sma/sma^index.sh. 


index  [MAKE  Target) 

WHEN  MADE:  Makes  %{PREFIX)^chap.in  (and  maybe  also  t{PREFIX)chQp.vs), 

${INDEX_FLAGS)  (MAKE  Macro) 

VALUE:  The  flags  for  the  SKETCH  index  program.  Usual  default: 
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${INSTALL_DIRECTORY)  [MAKE  Macro) 

${INSTALL_DIRECTORY)  [UNIX  Environment.  Variable] 

VALUE:  The  directory  in  which  files  are  installed  by  the  backup_vislall  and 
release_tnslall  make  targets. 

Must  be  set  in  c.s/;.rc  files.  %{ISSTALL_DIRECTOR^')  is  a  UNIX  Environment 
variable  turned  by  make  into  a  make  macro. 

${INSTALL_FILES)  [MAKE  Macro] 

VALUE:  A  list  of  all  files  that  are  to  be  installed  by  the  backap_inslall  and  release^inslall 
make  targets.  Default  value: 

"${1NSTALL_S0URCE_FILES)  $(1NSTALL_TARGET_F1LES)". 

$(INSTALL_RCFILES)  [MAKE  Macro] 

VALLT:  A  list  of  all  .re  source  files  that  are  to  be  installed  by  the  backup_inslall  and 
release_i7if<lall  make  targets.  Default  value:  ""  in  a  package  directory  and 

"inst alLcsh.rc  instalLsketch.rc" 

ill  a  global  directory. 

${INSTALL_SOURCE_FILES)  .  [MAKE  Macro) 

VALUE:  A  list  of  all  source  files  that  are  to  be  installed  by  the  backup_inslaU  and 
release_instull  make  targets.  Default  value: 

"make  makefile. mk  S;(HFILES)  $(SHF1LES)  $(DEM0_LF1LES) 
$(DEMO_CLFILES)  ${1NSTALL_RCFILES) 
$(OTHERJNSTALL_SOURCE_FILES)". 

$(INSTALL_TARGET_FILES)  [MAKE  Macro] 

VALUE:  A  list  of  all  target  files  that  are  to  be  installed  by  the  backup_inslall  and 
Telease_inslall  make  targets.  Default  value: 

"${LHF1LES)  $(PREFIX)_chap.in  COUNT 
${OTHERJNSTALL_TARGET_FILES)". 

in  a  package  directory,  and 

"${LHF1LES)  COUNT  $(0THERJNSTALL_TARGET_F1LES)". 
in  a  global  directory. 
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.1  [UNIX  File  Extension) 

FILE  FORMA.T;  A  LISP  source  file.  Can  be  loaded  directly  into  LISP  by  the  LISP  load 
function,  or  made  into  a  .ex,  .0,  .s,  .Ih,  or  .ou  file. 

A  ./  file  is  made  into  a  .ex  file  directly,  without  intervening  .5  or  .0  files, 
by  load'\n%  the  ./  file  into  %{L1SP)  and  duinplisp’\ng  the  result  to  the  .ex 
file. 


•Ic  [UNIX  File  Extension) 

FILE  FORMAT:  A  C  language  source  file  containing  lambda,  nlambda,  or  macro  functions. 

Compilation  of  this  file  into  assembly  language  is  done  specially  by  run¬ 
ning  the  compiler  output  through  special  filters  so  that  the  object  file  will 
fit  into  the  LISP  interpreter  environment.  Can  be  made  into  a  .0,  .s,  or 
.7it  file  (all  %{LHFILES)  are  all  made  first). 


$(LCFILES)  [MAKE  Macro) 

VALUE:  .4  list  of  all  the  .Ic  files  in  the  package.  These  are  assumed  to  be  source  files. 
Default  value: 


$(LD_FLAGS)  [MAKE  Macro) 

V.^LUE:  The  flags  for  the  UNIX  cc(l)  program  when  it  is  used  to  call  ld{l)  to  produce  an 
executable  program.  Usual  default: 

$(LFILES)  [MAKE  Macro) 

VALUE:  A  list  of  all  the  ./  files  in  the  package.  These  are  assumed  to  be  source  files. 
Default  value: 

"%{COMMON_LFILES)  %{COMPILE_LFILES) 

%{LOAD_LFILES)  %{DEMO_LFILES) 

%{OTHER_LFILES)''. 


.Ih  [UNIX  File  Extension) 

FILE  FORMAT:  A  C  definitions  file,  like  a  .h  file,  which  is  made  from  a  .1  file  via  the  *C- 
definition-code-port*  faciVity  (see  the  SKETCH  objects  package).  Can  be 
made  from  a  .1  file. 
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$(LHFILES)  [MAKE  Macro] 

VALUE:  A  list  of  all  the  package  .III  files  that  must  be  made  from  other  files.  All  of  these 
files  must  be  made  before  any  invocation  of  $(CC)  or  ${LINT).  Unfortunately, 
this  is  not  easily  expressed,  so  removal  of  a  .Ih  file  and  any  files  dependent  upon 
it,  and  remaking  the  .lli  file,  must  be  done  by  hand  whenever  something  is  done 
that  might  change  the  .Ih  file. 

However,  making  all  or  lint  will  make  all  the  ${LHFILES)  first. 

Default  value: 

WARNING:  If  you  change  anything  that  would  change  a  .Ih  file,  you  should  remove  by 
hand  any  file  that  would  be  affected  and  do  a  ""make  alt".  Or  you  may  simply 
do  a  ""make  clean  alt". 

WARNING:  These  files  are  all  removed  by  cleaning. 

$(LHJLISZT)  [MAKE  Macro] 

VALUE:  The  name  of  the  LISP  compiler  environment  used  to  make  .Ih  files  from  ./  files. 
Usual  default:  "’%{LISZT}"". 

$(LIBRARIES )  [MAKE  Macro] 

VALUE:  The  library  flags  and  file  names  for  the  UNIX  cc(l)  program  when  it  is  used  to 
call  ld{l)  to  produce  an  executable  program.  These  flags  and  names  are  placed 
after  the  files  being  loaded,  as  opposed  ${LD^LAGS)  which  appear  before  the 
files  being  loaded  in  the  Id  argument  list.  Default  value: 

link  [MAKE  Target] 

VALUE:  Executes— 

^LN)  ^LNJ^LAGS)  %{LINKJ)IRECTORY)/ file  . 

(notice  the  .  at  the  end  denoting  the  current  directory)  for  every  file  in 
${LINK^ILES)  that  is  not  readable  in  the  current  directory.  This  links  the  file 
in  %{LINK^IRECTORY)  to  the  file  in  the  current  directory.  Note  that 
%{LINhU)IRECTORY)  defaults  to- 

. ./.  ./src/$(FA  CKA  GEJ)IRECTOR  Y) 
in  a  package  directory,  and  to— 

../src 

in  a  global  directory,  while  %{LNJ'LAGS)  defaults  to  ‘—s’,  so  that  the  links  are 
normally  symbolic. 

Normally  you  must  first  do  some  linking  by  hand  to  get  SKETCH  make  to 
work;  namely  you  must  do— 

In  -s  <link_directory>/{make, makefile. mk}  . 

You  must  also  be  sure  ../csh.rc  or  csh.rc  is  defined. 

Link.packages  passes  to  each  package  make  the  definition— 
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LlNKJDlRECTORY=../$(LlNI'L_DlRECTORY)/<package_directory> 

Link  is  defined  with  a  double  colon  ::  and  can  therefore  be  added  to  by  defining 
new  entries  such  as— 

link:: 

if  test  !  -r  file;  \ 

then  ${LA0  %{LN_FLAGS)  %{LINK_DIRECTOR't')/?i\t  fi 

$(LINK_DIRECTORY)  [M.\KE  Macro] 

VALUE:  The  directory  into  which  %{LINKJFILES)  are  linked  by  the  link  make  target. 

Default  value:  "../../src/${PACl'CAGE_DlRECTORY)"  in  a  package  directory, 
and  "../src"  in  a  global  directory. 

Link. packages  supplies  the  definition— 

LINK_DIRECTORY= 

../${L1NK_DIRECT0RY)/%%{PA  CKA  GE_DIRECTOR 
to  each  package  make. 

$(LINK_FILES)  [MAKE  Macro] 

VALL^:  A  list  of  all  the  files  in  the  package  that  are  linked  by  the  link  make  target. 
Default  value:  "${SOURCE_FILES}  ^LNFILES)". 


${LINT)  JMAKE  Macro] 

VALUE:  The  name  of  the  UNIX  lini(l)  program.  Usual  default: 

psearch  smk/smk_lint.sh. 

This  default  lint  program  gets  rid  of  warning  messages  of  the  following  kinds: 

...  defined  (...),  but  never  used 
returns  value  which  is  always  ignored 
returns  value  which  is  sometimes  ignored 


lint  (MAKE  Target] 

WHEN  MADE:  Makes  .nt  files  corresponding  to  all  %{CFILES)  and  %{LCFILES).  First 
makes  all  ^LHFILES). 
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$(LINT_FLAGS)  [MAKE  Macro] 

VALUE:  The  flags  for  the  UNIX  program.  These  should  not  include  flags  for  the 

macro  preprocessor  cpp,  the  loader  ld{l),  and  cc(l),  which  are  separate.  Usual 
default: 

$(LINTJLIBRARIES)  [MAKE  Macro] 

VALUE:  The  library  flags  and  file  names  for  the  UNIX  program.  These  flags  and 

names  are  placed  after  the  files  being  linted,  as  opposed  %{LINTJ'LAGS)  which 
appear  before  the  files  being  linted  in  the  lint  argument  list.  Default  value: 
"${LIBRARIES)'\ 


$(LISP)  [MAKE  Macro] 

VALUE:  The  name  of  the  LISP  evaluator  program.  Usual  default:  "${SKETCH)". 

$(PREFlX)_lisp  [MAKE  Target] 

VALUE:  A  version  of  lisp  made  by  executing 

{load  ^PREFIX]Joad) 

in  ${LISP)  after  making  ^OFILES). 

^^lisp  [MAICE  Target] 

VALUE:  Makes  #/isp  the  same  way  as  %{PREFIX)_lisp  is  made. 

list  [MAKE  Target] 

VALUE;  Outputs  the  names  of  the  files  in  %{LIST_FILES)  to  the  standard  output,  one 
name  per  line. 

List. packages  prefixes  each  name  in  a  paw:kage  directory  by 
‘${PA  CKAGE_DIRECTOR  Y)/'. 

${LISTJF'ILES)  (MAKE  Macro] 

VALUE:  A  list  of  all  the  files  in  the  package  that  are  listed  by  the  list  make  target. 
Default  value:  ''%{SOURCE_FILES)" . 
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$(LISZT)  [MAKE  Macro) 

V.aLUE:  The  name  of  the  LISP  compiler  program.  Usual  default;  ''%{SKETCHCOM)" . 


$(PREFIX)_liszt  [MAKE  Target] 

VALUE:  A  version  of  liszt  made  by  executing 

[load  ^PREFlX)_compile) 

in  %{LISZT)  after  making  %(OFILES). 

^liszt  [MAKE  Target) 

VALUE:  Makes  ifliszt  the  same  way  as  ^PREFlX)_l^s^t  is  made. 


${LISZT_FLAGS)  [MAKE  Macro] 

VALUE:  The  flags  for  the  UNIX  liszt{l)  program.  Usual  default;  "-q".  Use  the  value 
to  get  verbose  output. 


${LN)  [MAKE  Macro) 

VALUE;  The  name  of  the  UNIX  /7){l)  program.  Usual  default:  "In". 

$(LNFILES)  [MA;KE  Macro) 

VALUE:  A  list  of  all  the  symbolic  links  in  the  package.  Default  value;  "make"  [make  is 
usually  linked  to  ../package_inake.sh). 


$(LN_FLAGS)  [MAKE  Macro) 

VALUE;  The  flags  for  the  UNIX  /n(l)  program.  Usual  default:  "s". 


load  [MAKE  Target] 

WHEN  M\DE:  Makes  %(PREFIX)Joad.o. 


$(LOADJLFILES)  [MAKE  Macro) 

VALUE:  A  list  of  all  the  ./  files  in  the  package  that  are  included  in  %{PREFIX)Jload.l  but 
not  %{PREFIX)_compik.l.  These  are  assumed  to  be  source  files.  Default  value: 

tttt 
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.ma  [UNIX  File  Extension] 

FILE  FORMAT:  A  wannal  source  file.  Gan  be  made  into  a  .tr^  ,sp,  .v$^  .vo,  .jis,  .no,  or  .he 
file.  Is  made  into  a  ./r  file  by  applying  the  %{MANVAL)  program  to  add 
glossary  entries  from  the  ${SOURCE_FILES)  and  by  passing  the  result 
through  p*c(l),  0771(1),  and  ^6/(1). 

$(MAFILES)  [MAKE  Macro] 

VALUE:  A  list  of  all  the  .ma  files  in  the  package.  These  are  assumed  to  be  source  files. 
Default  value: 

$(MAKE)  [MAKE  Macro] 

VALUE:  The  name  of  the  UNIX  7nake{l)  program,  relative  to  the  directory  in  which  it 
will  operate.  Usual  default:  "make*. 


make  [UNIX  File) 

VALUE:  Make  is  a  UNIX  command  file  that  replaces  (modifies)  the  standard  UNIX  make 
(1)  command.  Make  is  usually  symbolically  linked  to  ../package^make.sh  in  a 
package  subdirectory,  or  to  global_make.sh  in  a  global  directory. 

..  package^make.sh  generally  begins  with 

#!;'bin/csh  T 
if  (-r  csh.rc)  then 

source  csh.rc 
else  if  (-r  ../csh.rc)  then 
source  ../csh.rc 

else 

source  ../../csh.rc 
endif 

and  ends  with 

exec  psearch  smk/smk_make.sh  $argv:q 
It  does  not  have  to  contain  anything  else. 

global^make.sh  is  similar  but  begins  with 

#!/bin/csh  -f 
if  (-r  csh.rc)  then 

source  csh.rc 

else 

source  ../csh.rc 
endif 

and  ends  with 

exec  psearch  smk/smk_makeglobal.sh  $argv:q 
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${MAKE_FLAGS)  [MAKE  Macro] 

VALUE:  The  flags  for  the  UNIX  make(\)  program.  Usual  default: 

$(MANUAL)  [MAKE  Macro] 

VALUE:  The  name  of  the  SKETCH  manual  program.  Usual  default: 

psearch  s7na/sma_manual.sli. 

manual  [MAKE  Target] 

WHEN  MADE:  Prints  a  complete  manual  by  making  the  following  in  order:  title. vo, 

index. packages,  global_index.vo,  and  chap. packages. 

This  make  target  can  only  be  made  in  a  global  directory. 

$(MANUAL_FLAGS)  [MAKE  Macro] 

VALUE:  The  flags  for  the  SKETCH  manual  program.  Usual  default: 

.mk  [UNIX  File  Extension] 

FILE  FORMAT:  A  nia^'e  source  file. 

$(MKFILES)  [MAKE  Macro] 

V.M.UE:  A  list  of  all  the  .ink  files  in  the  package.  These  are  assumed  to  be  source  files. 

Default  value:  "makefile. mk". 


.no  [UNIX  File  Extension] 

FILE  FORMAT:  A  fictitious  file  which  when  made  causes  the  corresponding  .ns  file  to  be 
printed.  Can  be  made  from  a  .ma,  .do,  .tr,  or  .ns  file. 

${NROFF)  [MAKE  Macro] 

VALUE:  The  name  of  the  UNIX  nro^l)  program.  Usual  default:  "nro^-mc". 

${NROFF_JFLAGS)  [MAKE  Macro] 

VALUE;  The  flags  for  the  UNIX  nro^l)  program.  Usual  default:  "". 

•ns  [UNIX  File  Extension] 

FILE  FORMAT:  A  Ipr  source  file  (typically  output  by  nrof[\)).  Can  be  made  from  a  .ma, 
.do,  or  .tr  file.  Can  be  made  into  a  .no  file. 
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.nt  (UNIX  File  Extension] 

FILE  FORMAT:  The  output  from  //n/’ing  a  .c  file.  Can  be  made  from  a  .cor  ./c  file. 


.o  [UNIX  File  Extension] 

FILE  FORMAT:  A  binary  object  file  containing  a  program,  as  produced  by  a  compiler, 
such  as  those  for  LISP,  C,  and  FORTRAN.  LISP  object  files  can  be 
loaded  into  LISP  by  the  load  function,  and  others  by  the  chad  function. 
Can  be  made  into  a  .ex  file,  or  made  from  a  ./,  .c,  ./c,  .C5,  ./,  or  ,s  file. 

$(OFILES)  [MAKE  Macro] 

VALUE:  A  list  of  all  the  package  .0  files  that  must  be  made  from  other  files.  These  files 
are  made  by  ''make  alT.  Default  value: 

WARNING:  These  files  are  all  removed  by  cleaning. 


$( O THER.CLFILES )  [MAKE  Macro] 

VALUE:  A  list  of  all  the  .cl  files  in  the  package  that  are  not  in  ^DEMO^CLFILES). 
These  are  assumed  to  be  source  files.  Default  value: 


$(OTHER«DEMO_TARGET.FILES)  [M\KE  Macro] 

VALUE:  A  list  of  all  the  files  other  than  those  in  ^ALL^FILES)  that  should  be  made 
before  making  any  file  listed  in  ^DEMO_OUFILES).  E.g.,  the  .0  file  for  any  .c 
file  used  exclusively  by  the  demo.  Default  value: 


${OTHER.INSTALL_SOURCE_FILES)  [MAKE  Macro] 

VALUE:  A  list  of  all  source  files  that  are  to  be  installed  by  the  backup^xnstall  and 
release^install  make  targets,  but  which  are  not  listed  in  t{HFILES}j 
^SHFILES),  %{INSTALLJtCFILES),  ${DEMOJLFILES},  or 
^DEMO^CLFILES).  The  files  make  and  makefile.mk  should  also  be  excluded 
from  this  list.  Default  value: 

${OTHERJNSTALL«TARGETJ'ILES)  [MAKE  Macro] 

VALUE:  A  list  of  all  target  files  that  are  to  be  installed  by  the  backup^inatall  and 
release^xnstall  make  targets,  but  which  are  not  listed  in  %{LHFILES).  The  index 
file  %{PREFIX)^chap.xn  and  the  COUNT  file  should  also  be  excluded  from  this 
list.  Default  value: 
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${OTHERJ.FILES)  [MAKE  Macro] 

A  list,  of  all  the  ./  files  in  the  package  that  are  included  in  neither 
%{PREFlX)^load.l  nor  ${PREFIX)^compile.l,  and  are  not  in  %{DEMO_LFILES). 
These  are  assumed  to  be  source  files.  Default  value; 

${OTHER_PRINT_FILES)  [MAKE  Macro] 

VALUE:  A  list  of  all  the  printable  source  files  in  the  package  that  are  not  listed  else¬ 
where,  as  in  %{LFILES)  or  i{CFILES).  Default  value; 
"$(  O  THER_SO  UR  CE_FILES)". 

${OTHER_RCFILES)  [MAKE  Macro] 

VALL^E:  A  list  of  all  the  .rc  files  in  the  package  that  are  not  listed  in 
%{INSTALL_RCFILES).  These  are  assumed  to  be  source  files.  Default  value; 


^  O  THER.S  OURCE_FILES )  [MAKE  Macro] 

VALUE:  A  list  of  all  the  source  files  in  the  package  that  are  not  listed  elsew  here,  as  in 
^LFILES)  or  ${CF1LES).  Default  value: 

$(OTHER_TARGET_FILES)  [MAKE  Macro] 

VALUE;  A  list  of  all  the  non-source  files  in  the  package  that  are  not  listed  elsewhere, 
namely  in  ^LHILES),  $(OF/LES),  or  ^FILES).  These  files  are  made  by 
**makt  air.  Default  value: 

WARNING:  These  files  are  all  removed  by  cleaning. 


.ou  [UNIX  File  Extension] 

FILE  FORMAT:  A  copy  of  the  standard  output  of  some  program.  Can  be  made  from  a  ./ 
file  by  executing— 

(demo  ’<x>./  ^<x>.ou) 

in  the  %{DEMOJLISP)  program.  Can  be  made  similarly  from  a  .cl  pro¬ 
gram  using  %{DEMOJLISZT)  in  place  of  %{LISP). 

$(PACKAGE_DIRECTORY)  [MAKE  Macro] 

VALUE:  The  package  directory  name;  e.g.  "sar”  for  the  SKETCH  array  package. 
Default:  %{PREFIX). 

Must  be  the  sanje  as  %{PREFIX)  in  order  for  .packages  make  targets  in  a  global 
directory  to  work,  since  ^PACKAGES)  lists  only  one  name  per  package,  and 
presumes  that  this  name  is  both  the  %{PREFIX)  and 
%{PACKAGEJ)IRECTORY)  for  the  package. 
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${PACKAGE_LINK_FILES)  [MAKE  Macro] 

VALUE:  Link. packages  supplies  the  definition  — 

LINK_FILES=${PA  CK.A  GE_LINK_FILES) 

to  each  package  make.  Default  value:  ‘%%{SOURCE_FILES)  $${Z,NF/Z,£'S)’’.  Be 
sure  to  double  the  dollar  signs  in  any  definition  you  supply. 

${PACKAGE_LIST_FILES)  (MAKE  Macro] 

VALUE:  List. packages  supplies  the  definition— 

LIST_FILES=%(PA  CKA  GE_LIST_FILES) 

to  each  package  make.  Default  value:  ''$^SOURCE_FILES)'' .  Be  sure  to  double 
the  dollar  signs  in  any  definition  you  supply. 


$(PACKAGES) 

“global  directory” 
“package  directory” 
<make_target>. pack  ages 
global.demo. packages 


(MAKE  Macro] 
[SKETCH  Term] 
[SKETCH  Term] 
[MAKE  Target  Extension] 
[MAKE  Target  Extension] 


V.^UE:  ^{PACKAGES)  is  a  list  of  package  subdirectories  that  are  to  be  processed  by  the 
<\\\>  .packages  targets  of  this  global  directory.  These  subdirectories  need  not 
be  in  the  global  directory  itself  as  long  as  they  are  in  the  path  of  global  direc¬ 
tories  (and  can  be  found  by  /search  (tps)). 


Making  a  target  named  < target >  .pac/ra,(7es  in  the  global  directory  makes  the 
target  < target >  in  each  package  subdirectory  listed  in  ^{PACKAGES),  for 
each  package  target  <target>  whose  name  does  not  include  a  package  prefix. 


The  following  <taLTget> .packages  targets  pass  the  indicated  make  macro  values 
to  the  package  make  commands  when  they  execute— 


backup_install. packages 
clean_install. packages 
list.packages 
link.packages 


INSTALLJDIRECTORY= 
t{INSTALLJ)IRECTOR  Y) 
INSTALL_DIRECTORY= 
t{INSTALLJ)IRECTOR  Y) 
LIST_FILES= 

t{PA  CKA  GE_LIST_FILES) 
LINK_FILES= 

$(PA  CKA  GE_LINK_FILES) 
LINKJDIRECTORY= 

../t{LINKJ)IRECTOR  Y)  / 

$${PA  CKA  GEJ)IRECT0R  Y) 


Actually,  %{INSTALL^IRECTORY)  is  converted  to  non-relative  form  before  it 
is  passed,  but  ^{LINICJDIRECTORY)  is  not. 


Sometimes  it  is  desirable  for  demo. packages  to  pass  the  %{DEMO^ISP)  and 
%{DEMO_LISZT)  values  to  the  package  make,  so  there  is  a  variant  named 
global. demo. packages  that  does  this  by  passing- 
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DEMOMSP-=^DE^^OJ.ISP) 

DEMOMSZT^^DEMO^LISZT) 

When  defining  $[PACI<AGE^LIST^FILES)  and  ^PACKAGE^LINK^FILES} 
one  must  double  the  dollar  signs.  For  example— 

make  'PACKAGE^LIST^FILES=%%{HFILES)^  list. packages 


Making  a  target  not  of  the  form  .packages  in  a  global  directory  is  like 

making  the  target  in  a  package  directory,  except  that  targets  that  make  files 
whose  name  includes  ^(PREFIX)  or  ${PACKAGEJDIRECTORY}  cannot  gen¬ 
erally  be  made  in  the  global  directory.  However,  the  following  targets  work  in 
the  global  directory— 

clean^install  With 

backup Jnstall  ^IXSTALL^DIRECTOR  ))/${PA  CKA  GE^DIRECTOR^^ 

release^install  replaced  by  %{INSTALL^DIRECTORY). 

WARNING:  There  is  a  strange  bug  in  some  versions  of  the  UNIX  ma/:e(l)  that  causes  its 
-n  option  not  to  work  for  xx. packages  targets.  Use  MAKEJFLAGS=-n 
instead. 

$(PATH)  •  [MAKE  Macro] 

$(PATH)  [UNIX  Environment  Variable] 

VALUE:  A  list  of  colon  (:)  separated  directory  names.  These  directories  are  searched  in 
order  for  programs  to  run  by  cs/i,  sh,  and  psearch.  The  same  directories  are 
searched  in  order  by  /search  for  data  files. 

Must  be  set  in  csli.rc  files.  %{PATH)  is  a  UNIX  Environment  variable  turned  by 
make  into  a  make  macro. 

${PIC)  [MAICE  Macro] 

VALUE:  The  name  of  the  UNIX  pic{l)  program.  Usual  default:  ’’pic”. 

WARNING:  Do  not  use  ptc  constructs  in  files  to  be  nro^ed. 

${PIC  J'LAGS)  [MAKE  Macro] 

VALUE:  The  flags  for  the  UNIX  pic(l)  program.  Usual  default: 
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${PREFIX)  [MAKE  Macro] 

VALUE:  The  package  name  prefix.  E.g.  "sar"  for  the  SKETCH  array  package,  which 
prefixes  file  names  such  as  "sar_array.r’  and  C  code  global  names  such  as 
"sar_array". 

${PRINT)  [MAKE  Macro] 

VALUE:  The  name  of  the  UNIX  prtnt{l)  program.  Usual  default:  "print".  Use  the  value 
"imprint"  with  an  IMAGEN  printer. 


print  [MAKE  Target] 

WHEN  MADE:  Makes  the  WC  file  and  $iPRINT)’s  WC  and  ${PRINT_FILES),  the  latter 
in  alphabetical  order. 

$(PRINT_FILES)  [MAKE  Macro] 

V.4LUE:  A  list  of  all  the  source  files  in  the  package  which  are  to  be  printed  by  the  make 
print  target.  Default  value: 

'^LFILES)  %[CLFILES)  %{HFILES)  ${CF1LES) 

^LCFILES)  ^CSFILES)  ^FFILES) 

${MI<FILES)  $iSHFILES)  $(RCFILES; 

^(O  THER_PRINT_FILES)" . 

Because  OTHER_PRL\'T_FILES  is  defined  by  default  to  be 
%{OTHER_SOURCE_FILES),  PRINT_FILES  is  by  default  just  the  same  as 
SOURCE_FILES  with  .ma  and  .do  files  omitted. 

$(PRINT_FLAGS)  [MAKE  Macro] 

VALUE:  The  flags  for  the  UNIX  print{l)  program.  Usual  default:  Use  the  value  "-2 - 

O"  with  an  IMAGEN  printer. 

print_with_count  [MAKE  Target] 

WHEN  MADE:  Makes  the  COUNT  file  and  t{PRINT)'s  COUNT  and  t{PRlNT_FlLES}, 
the  latter  in  alphabetical  order. 


$(RCFILES)  (MAKE  Macro] 

VALUE;  A  list  of  all  the  .rc  files  in  the  package.  These  are  assumed  to  be  source  files. 
Default  value;  "${INSTALL_RCFILES}  %{OTHER_RCFILES)" . 
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$(RELEASE)  [MAKE  Macro] 

VALUE:  The  name  of  the  TPS  release{tps)  program.  Usual  default:  "release*. 

${RELEASEJ'LAGS)  [MAKE  Macro] 

VALUE:  The  flags  for  the  TPS  release(tps)  program.  Usual  default: 

release_install  [MAKE  Target] 

VALUE:  Releases  %{INSTALLJ*ILES)  in  the  directory 

%{INSTALLJ)IRECTOR  }^/%{PA  CKA  GEJ)JRECTOR  >0 
by  using  re/ease(tps)  with  the  —D  and  —6  options. 

In  the  global  directory,  ^INSTALL^IRECTOR)^  is  used  in  place  of 
%(INSTALL^DIRECTORY)/${PACKAGEJ)JRECTOR  Y). 


rel^ase_instalLsource  [MAKE  Target] 

VALUE:  Releases  ^INSTALL^SOURCE^ILES)  using  re/ease(tps). 

reIease_source  |M.A.KE  Target) 

VALUE:  Releases  ${SOURCE^ILES}  using  release(tps). 


.s  [UNIX  File  Extension] 

FILE  FORMAT:  A  non-macro,  assembly  language  source  file.  Can  be  made  into  a  .o  or  ex 
file,  or  made  from  a  ./,  .c,  ./c,  ./,  or  .cs  file.  These  files  should  not  be  used 
as  source  files,  as  they  are  cleaned  out  by  s. clean.  Use  .cs  files  instead. 


.sh  [UNIX  File  Extension] 

FILE  FORMAT:  A  sh{l)  or  csh{l)  source  file. 

${SHFILES)  (MAKE  Macro] 

VALUE:  A  list  of  all  the  .sh  files  in  the  package.  These  are  assumed  to  be  source  files. 
Default  value: 


$(SKETCH)  (MAKE  Macro] 

VALUE:  The  name  of  the  SKETCH  program.  Usual  default:  sketch. 
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${SKETCHCOM)  [MAKE  Macro] 

VALUE:  The  name  of  the  SKETCH  compiler  program.  Usual  default:  sketchcom. 

sketch. rc  (UNIX  File] 

VALUE:  A  file  in  the  global  directory  that  defines  the  directories  used  by  sketch.  It 
should  have  roughly  the  form-* 

(sstatus  cache*search-path  (<this-directory>  <next-directory>  ...)) 

(sstatus  catalog-search-path  (<this-directory>  <next-directory>  ...)) 

(sstatus  data-search-path  (<this-directory >  <next-directory>  ...)) 

(sstatus  font-search-path  (<this-directory>  < next-directory  >  ...)) 

(sstatus  load-search-path  (<this-directory>  < next-directory  >  ... 

<some-directory  > /lisp/lisplib)) 

(setq  *display-file-name*  ydev/<display-device>) 

(setq  *camera-file*  7dev/<camera-device>) 

where  the  chain  of  directories  to  be  searched  for  SKETCH  program  and  data 
files  is  <this-directory>  < next-directory >  ...,  and  the  FRANZ  LISP  library  is 
int  <some-directory> /lisp/lisplib.  Relative  directory  names  must  not  be  used 
in  sketch. rc. 

smk_lint.sh...  [UNIX  Command] 

SREALJLINT  [UNIX  Environment  Variable] 

equivalent  TO:  but  runs  the  output  through  fgrep{l)  to  remove  all  warning 

messages  of  the  form— 

...),  but  never  used... 

...returns  value  which  is  always  ignored... 

...returns  value  which  is  sometimes  ignored... 

...nonportable  character  comparison... 

...File  with  unknown  suffix... 

NOTE:  The  UNIX  lint  command  may  be  changed  for  this  shell  file  by  defining  the 
environment  variable  REALULINT  to  equal  a  substitute. 

${SOURCE  J'lLES)  (MAKE  Macro] 

VALUE:  A  list  of  all  the  source  files  in  the  package.  Symbolic  links  listed  in  %{LNFILES) 
are  not  included.  Default  value: 

'*%{LFILES)  %{CLFILES}  ${HFILES}  %{CFILES) 

%{LCFILES)  ^CSFILESj  ${FFILES} 

${MAFILE^  i{DOFILES}  ${MKFILES) 

%{SHFILES}  ${CFILES)  ${OTHER^SOURCEJ^ILES}\ 
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.sp  [UNIX  File  Extension) 

FILE  FORMAT:  The  output  of  the  ^SPELL)  program  run  against  a  .tr  file  and  filtered 
through  the  ^(COLUMNS)  program.  Can  be  made  from  a  .ma,  .do,  or  .tr 
file. 

${SPELL)  [MAKE  Macro] 

VALUE:  The  name  of  the  UNIX  spell{l)  program.  Usual  default:  "spelt'. 


spell 

WHEN  MADE:  Makes  %(PREFlX)_cliap.sp. 

${SPELL_FLAGS) 

VALUE:  The  flags  for  the  UNIX  spell{l)  program.  Usual  default: 
${TBL) 

VALUE:  The  name  of  the  UNIX  tbl{l)  program.  Usual  default:  "tbP. 
${TBL_FLAGS) 

vaLIT;:  The  flags  for  the  UNIX  lbl{l)  program.  Usual  default: 
$(TITLE) 

VALUE:  The  title  of  the  package  chapter  or  appendix. 


[MAKE  Target] 
[MAKE  Macro] 
[MAKE  Macro] 
[MAKE  Macro] 
[MAKE  Macro] 


.tr  [UNIX  File  Extension] 

FILE  FORMAT:  A  troff  source  file.  Can  be  made  into  a  .vo,  .vs,  .sp,  .ns,  .no,  or  .he  file,  or 
made  from  a  .ma  or  .do  file.  P«c(l),  eqn{l),  and  lbt{l)  must  be  run  to 
make  a  .tr  file;  only  troff  will  be  run  on  the  .tr  file  itself. 

•VO  [UNIX  File  Extension] 

FILE  FORMAT:  A  fictitious  file  which  when  made  causes  the  corresponding  .vs  file  to  be 
printed.  Can  be  made  from  a  .ma,  .do,  .tr,  or  .vs  file. 


•VS  [UNIX  File  Extension] 

FILE  FORMAT:  A  Ipr  -n  source  file.  Can  be  made  into  a  .vo  file,  or  made  from  a  .tr,  .ma, 
or  .do  file. 
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$(VS_PRINT)  [MAKE  Macro] 

VALUE:  The  name  of  the  UNIX  program  that  prints  .vs  files.  Usual  default;  "Ipr  -n". 
Use  the  value  "Ipr  -n  -Pip"  with  an  IMAGEN  printer. 

${VS_PRINT_FLAGS)  [MAKE  Macro] 

VALUE:  The  flags  for  the  ${  V'SLFR/A'T)  program.  Usual  default; 


wc 

WC 

WC 

WHEN  MADE: 


[MAKE  Target] 
[MAKE  Target] 
[UNIX  File  Name] 

Applies  u;c{l)  to  ${SOURCE_FILES)  and  puts  the  result  into  the  file 
named  WC.  If  there  are  any  symbolic  links  in  %{LNFILES),  an  Is  -/  listing 
of  these  is  appended  to  WC. 
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1.  CHAPTERS.  The  SKETCH  manual  is  written  using  the  ME  macro  package  for  the 
trof[\)  text  processing  system.  The  manual  is  organized  into  chapters,  one  per  package. 
Each  chapter  consists  of  ordinary  manual  sections,  followed  by  a  glossary.  The  glossary 
is  embedded  in  the  source  code. 

A  SKETCH  chapter  is  printed  by  the  command 

moke  chap 

which  invokes 

S777a^v}(u}val  sh  -i '%( CHAPTER TITLEE  %lPREFIX)_chQp.ma 
%{GLOSSARy_FILES) 

followed  by  \flpic(l).  fle(in(l),  and  IroJJ  The  ordinary  package  manual  sec¬ 

tions  are  in  tlie  file  %{PREFJX)_chap  ina,  where  ^PREFIX)  is  the  package  prefix.  The 
glossary  entries  are  in  the  files  listed  in  ^GLOSSAR)’_FILES),  which  by  default  is  just 
the  list  of  all  code  source  files  (e.g.  ^LFILES)  and  ^CFILES):  see  the  appendix  titled 
MAKING  FILES).  ^{CHAPTER)  is  the  chapter  number,  and  ^TITLE!)  the  chapter  title. 

The  file  $(P/?£’P/A*)_chap.ma  is  written  as  a  sequence  of  sections  each  beginning 
with  a  ME  section  header— 

.sh  1  SECTION  TITLE. 

The  SECTION  TITLE  should  be  capitalized  and  terminated  by  a  period.  Spaces  included 
in  the  SECTION  TITLE  must  be  preceded  by  a  backslash  \. 

If  ^{CHAPTER)  is  a  single  capital  letter,  instead  of  a  number,  everything  is  the 
same  except  the  result  is  called  an  appendix  instead  of  a  chapter. 

2.  GLOSSARY  ENTRIES.  Glossary  entries  are  included  in  source  files.  The  method 
of  inclusion  depends  upon  the  language  in  which  the  source  file  is  written.  For  example,  a 
./  file  prefixes  each  glossary  entry  line  by  ‘;<tab>*,  except  for  blank  entry  lines  for  which 
the  <tab>  may  be  omitted.  A  simple  example  is- 

;  .En{  some-function  "  'g.j5ome-argument)”  "(LISP  Function)'* 

;  .Pa  RETURNS 

;  Some  value  computed  from  g^some-argument. 

Another  simple  example  in  a  .c  file  is 

r 

.En  ""  some-function  "  (g_some- argument)"  "(C  Function]" 

.Pa  RETURNS 

Some  value  computed  from  g_some- argument. 
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The  .En  TROFF  command  line  is  required  at  the  beginning  of  each  glossary  entry. 
Its  4  arguments  are  simply  concatennted  to  form  an  output  line:  except  that  the  second 
argument  is  suirounded  by  \fB  and  \fP  to  make  it  boldface,  and  the  fourth  argument  is 
right  adjusted  in  the  output  line  instead  of  being  put  next  to  the  other  arguments. 

The  fourth  argument  is  intended  to  describe  the  role  of  the  name  that  is  the  second 
argument.  The  following  is  a  list  of  standard  fourth  arguments— 


[.Argument  Prefix] 

[C  F unction] 
jC  Macro] 

[C  Global  Variable] 

[C  Global  Constant] 

[C  Structure  Element^ 
[LISP  Function] 

ILISP  Special  Function] 
(LISP  Macro] 

[LISP  Global  \’ariablej 
[LISP  Global  Constant] 
[LISP  Property] 


[MAKE  Macro] 

[MAKE  Target] 

[SKETCH  Attribute  Object] 
[SKETCH  Attribute  Macro] 
[SKETCH  Object] 

[SKETCH  Term] 

[SKETCH  Type  Object] 
[SKETCH  Type  Macro] 
|TROFF  Command] 

[UNIX  Command] 

[UNIX  File  Extension] 


The  .Cv  TROFF  command  will  have  the  same  effects  as  a  .En  command,  except  it 
does  not  start  a  new  glossary  entry,  but  continues  the  current  one.  It  provides  a  way  of 
specifying  several  different  titles  for  one  entry. 

There  are  problems  in  the  glossary  sorting  system  (see  below)  which  cause  it  to  fail 
if  either  of  the  first  two  arguments  to  .En  or  .Cn  contain  spaces  or  tabs.  In  these  two 
arguments  use  \0  instead  of  \(space).  Troff  l  rentes  \0  as  a  space  the  width  of  one  digit. 

The  .Xn  TROFF  command  can  be  used  to  add  extra  lines  to  a  .En  or  .Cn  command. 
The  extra  line  is  indented  to  the  spot  at  which  \kl  last  appeared  in  a  previous  line,  as  in 

;  .En  (  some-function  "  \krg_argument-l  ’g_argument-2"  **[L1SP  Function]*' 

;  .Xn  "'g_argument-3  *g_argument-4)" 

Other  letters  can  be  used  in  place  of  I:  see  .Xn  in  the  glossary. 

Glossary  entries  are  included  in  various  kinds  of  files  according  to  the  rules  in  Table 
1.  In  order  for  glossary  entries  to  be  correctly  extracted,  each  file  must  have  an  extension 
that  specifies  the  language  in  which  it  is  written. 

The  glossary  is  alphabetized  by  sorting  each  entry  according  to  the  second  argument 
of  the  .En  TROFF  command  that  begins  the  entry.  An  index  essentually  consists  of  a 
glossary  with  everything  outside  .£*71,  .Cn,  and  .ATn  commands  discarded.  For  index  pur¬ 
poses,  .Cn  and  .En  are  treated  identically,  and  both  start  an  new  index  entry.  These 
index  entries  are  sorted  on  the  second  argument  to  the  .En  or  .Cn  commands. 

3*  THE  HELP  FACILITY.  The  on-line  manual,  or  help  facility,  is  not  yet  completely 
implemented. 

The  first  step  in  the  making  of  an  on-line  manual  is  to  make  the 

%(PREFL\%chap.he 

help  file  from  the 
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TABLE  1 

RULES  FOR  INCLUDING  GLOSSARY 

ENTRIES  IN  FILES 

./  file: 

Preface  all  entry  lines  with  a  ‘;<tab>\ 

Omit  the  <tab>  for  blank  entry  lines. 

End  entries  with  a  line  not  beginning  with  ‘;<tab>’. 

.sli  file: 

Preface  all  entries  with  a  <  <\DOCUMENTATION’  line. 
End  entries  with  a  ‘DOCUMENTATION’  line  for  sh  files, 
and  a  ‘\DOCUMENTATION’  line  for  csh  files. 

x.  ./»,  xs, 
or  ./c  file: 

Preface  all  entries  with  a  line. 

End  entries  with  a  line. 

.nia  or  .do 
file: 

Preface  all  entry  lines  with  ‘.V'<tab>\ 

Omit  the  <tab>  for  blank  entry  lines 

End  entries  with  a  line  not  beginning  with  ‘.V'<tab>’. 

.ink'  file: 

Preface  all  entry  lines  with  a  ‘7^<tab>\ 

Omit  the  <tab>  for  blank  entry  lines. 

End  entries  with  a  line  not  beginning  with  ‘#<tab>\ 

TABLE  1 


%( PREFIX )^cliap.ma 

file  by  running  the  .jna  file  through  ^6/(1)  to  make  a  ,tr  file,  and  then  through  nroJ}{l)  and 
co/(l)  to  make  a  .he  file.  Col  filters  the  output  of  nroff  to  remove  all  special  motion  con¬ 
trol  characters,  except  for  backspace  in  sequences  such  as— 

_(backspace)X 

which  are  used  to  underline  the  characters  such  as  X. 


The  .he  file  actually  has  only  glossary  entries,  and  not  the  rest  of  the  manual 
chapter.  There  are  also  extra  lines  of  the  form— 


//////////////////////////////.En  <name> 

beginning  the  glossary  entry  with  the  given  <name>  (second  argument  to  .£*«),  and 
■//■// //////#7^/-/////////////ACn  <extra-name> 
for  each  <extra-name>  defined  by  a  glossary  entry  (second  argument  to  .Cn). 
Making— 

%(PREFIX)_chap.ho 

will  have  the  effect  of  printing 


ifPREFIXJ^chap.he 

in  such  a  way  that  it  can  be  proofread.  This  proofreading  is  necessary  to  check  that 
problems  are  not  caused  by  the  fact  that  nroff  cannot  fit  as  many  characters  on  a  line  as 
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irojf.  Pay  special  attention  to  glossary  entry  headers. 

In  the  future  programs  ^^ill  be  provided,  hopefully  based  on  the  UNIX  refer  package, 
to  index  the  Jie  files  and  rapidly  retrieve  glossary  entries'  therefrom. 

4.  THE  INDEX.  If  the  -2  option  is  used  with  sma^manual.shj  then  when  troff  is  run  on 
the  output  of  sma^fnanual.sh^  an  index  file  will  be  written  into  the  standard  error  file. 
Several  such  index  files  many  be  combined  into  an  appendix  by  the  sma^tudex.sh  UNIX 
command. 

If  the  apparatus  described  int  eh  appendix  titles  MAKING  FILES  is  used,  index  files 
are  made  automatically  as  a  side  effect  of  printing  the  manual  chapter.  The  manual 
chapter  (or  appendix)  has  a  principal  source  file  named  <xxx>.ma,  and  the  associated 
index  file  is  named  <xxx>.w.  A  global  index  that  includes  all  the  package  .m  files  can 
be  printed  by  making  the  target  fast^mdex  or  sloxv^index  in  the  global  directory  which  is 
a  parent  of  the  package  directory.  See  the  appendix  titled  MAKING  FILES  for  more 
details. 

5.  HITLIST 

(l)  Finish  the  help  facility. 

6.  GLOSSARY. 

sma_count.sh  [-c]  file  ...  [UNIX  Command] 

EFFECT:  Counts  non-blank  manual  lines  and  code  lines,  and  reports  the  results.  The 
totals  are  reported  for  each  file  name  directory,  prefix,  and  extension,  along 
with  a  grand  total.  A  file  name  is  of  the  form  — 

<  d  i  rec  tory  >/<prefix>_<  body  > .  <  extension  > 

where  only  the  last  /,  last  and  last  .  are  recognized  considered.  The  output 
is  lines  of  the  form  — 

<directory>/  <number  code  lines>  <number  manual  lines> 

<prefix>_  <number  code  lines>  <number  manual  Iines> 

.<extension>  <number  code  lines>  <number  manual  lines> 

followed  by  a  separator  line— 

y///////////w////////////7/ ////////////////// ////// 

followed  by  one  line  of  the  form  — 

<dir>/  <prefix>_  <body>  .<ext>  manual  lines>  <#codelines> 

for  each  file.  In  either  case  a  missing  directory  <dir>  is  denoted  by  \\  and  a 
missing  <prefix>,  or  extension  <ext>  by  ‘NONE’. 

Glossary  manual  lines  may  be  included  in  .sA,  .c,  .A,  ./c,  .cs,  .ma,  .do,  or  .mk 
files  with  .En  entries:  see  sma^manual.sh  for  the  scheme  used  to  include  such 
lines.  Non-glossary  lines  in  these  files  are  counted  as  code  lines,  except  for  .ma 
files  where  non-glossary  lines  are  counted  as  manual  lines,  .do  files  are  treated 
like  .ma  files,  though  they  usually  contain  no  glossary  lines.  Files  with  no 
extension  are  treated  like  .sh  files. 
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Blank  manual  and  code  lines  are  not  counted.  Certain  essentually  blank  lines, 
such  as  lines  containing  only  in  troff  input,  only  semi-colons  in  LISP  input, 
or  only  ' /*'  or  ‘*/’  in  C  input,  are  also  not  counted.  Blank  glossary  lines  are 
those  that  are  blank  in  this  sense  after  any  comment  header  (e.g.  the  ‘;<tab>' 
for  ./  files)  has  been  stripped  off. 

If  the  -c  option  is  present,  the  input  files  are  outputs  from  previous 
sina^count.sh  runs,  and  are  combined  to  produce  a  composite  input  file.  Any 
directory  part  to  each  input  file  name  is  added  to  the  beginning  of  the  direc¬ 
tories  listed  in  that  file. 

sma_index.sh  appendix-letter  ’appendix-title'  [index-file  ...]  [UNIX  Command] 

EFFECT.  A  troff/nroff  script  is  output  for  a  index  with  given  appendix-letter  and  title. 
The  index  files  are  .in  files  made  by  the  -i  option  to  sma_Tnanual.sh. 

The  appendix  letter  and  title  obey  the  same  rules  as  the  chapter  number  and 
title  do  for  sma^manual.sh.  In  particular,  single  capital  letters  should  be  used 
for  the  appendix  letter,  if  numbers  are  used,  a  chapter  will  be  created  instead 
of  an  appendix. 

NOTE:  The  nrofi  trofT  script  output  presumes  that  the  me  macro  package  will  be  input 
to  nroff  or  troff  separately. 

sma_manual.sh  [-i]  chapter-number  'chapter-title'  chapter-file  [UNIX  Command] 

[glossary-file  ...j 

EFFECT:  A  troff/nroff  script  is  output  for  a  chapter  with  given  number  and  title.  The 
initial  part  of  the  chapter  is  defined  by  the  chapter-file.  The  final  section,  enti¬ 
tled  "GLOSSARY**,  is  constructed  from  the  glossary- files,  if  present.  These  can 
be  ./,  .shy  .c,  .hy  ./c,  .cs,  .ma,  .dOy  or  .mk  files  with  .En  entries.  These  .En 
entries  must  be  included  as  comments  according  to  the  following  scheme- 


./  file:  Preface  all  entry  lines  with  a  ‘;<tab>'. 

Omit  the  <tab>  for  blank  entry  lines. 

End  entries  with  a  line  not  beginning  with  ‘;<tab>’. 


.sh  file: 

Files  with  no 
extension: 


Preface  all  entries  with  a  ‘:  <<\DOCUMENTATION'  line. 
End  entries  with  a  ‘DOCUMENTATION’  line  for  sh  files 
and  a  ‘\DOCUMENTATION’  line  for  esh  files. 


.Cy  .hy  .CSy 

or  Ac  file: 


.  Preface  all  entries  with  a  V*’  line. 
End  entries  with  a  ‘*/'  line. 


.7710  or  .do 
file: 


Preface  all  entry  lines  with  ‘.V*<tab>'. 

Omit  the  <tab>  for  blank  entry  lines. 

End  entries  with  a  line  not  beginning  with  ‘.V*<tab>’. 
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.inh  file:  Preface  all  entry  lines  with  a  ‘#<tab>’. 

Omit  the  <tab>  for  blank  entry  lines. 

End  entries  with  a  line  not  beginning  with  ‘^<tab>*. 

APPENDICES:  If  the  chapter  number  is  a  single  capital  letter,  an  appendix  will  be  created 
instead  of  a  chapter. 

-1  OPTION:  The  -i  option  causes  an  index  to  be  output  to  the  error  output  stream  during 
troff  processing.  The  $ma_indcx.sh  UNIX  command  can  process  this  index  to 
produce  final  output. 

NOTE:  The  nroff/troff  script  output  presumes  that  the  me  macro  package  will  be  input 
to  nroff  or  troff  separately. 
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1.  FRANZ  FIXES.  These  are  miscellaneous  bug  fixes  to  FRANZ  LISP.  They  are  indi¬ 
vidually  documented  in  the  glossary. 

2.  GLOSSARY. 

(atom  ...)  (LISP  Function] 

EFFECTS  XERSIONS:  Opus  38.92  only. 

FIXED  BUG;  Compiled  atom  incorrectly  returned  nfV  for  rec/or  and  vec/ori  values.  Inter¬ 
preted  aiovi,  however,  correctly  returned  i. 

(defconst  ...)  [LISP  Macro] 

FIXED  BUG;  FRANZ  de/coiiaf  does  not  declare  constants  to  be  special  symbols  if  it  is  just 
loaded  in. 


(defprop  -..)  [LISP  Macro] 

FIXED  BUG:  FRANZ  defprop  does  not  compile  function  values  for  a  property.  The  fixed 
version  compiles  /am6da’s,  lexpr's,  and  macro's. 


liszt  ...  (UNIX  Command] 

(liszt-declare  Ldeclaration  ...)  [LISP  Nlambda  Function] 

EQUIVALENT  TO:  Standard  FRANZ  liszt,  but  modified  so  that  it  may  be  called  with  no 
arguments,  will  read  and  execute  LISP  expressions  in  its  standard 
input,  will  remember  any  special  declarations  made  when  dejvar  or 
defconst  are  executed,  and  can  be  saved  by  dumplisp  to  make  a  new 
version  of  the  compiler. 

[status  feature  complr)  is  set  in  this  compiler  and  may  be  used  to  con- 
ditionalize  code  for  loading  or  execution  inside  the  compiler. 

New  versions  of  the  compiler  made  by  dumplisp  will  not  read  in  Aiszirc 
files. 

LISZT-DECLARE:  In  general  any  call  to  liszt-declare  will  remember  things  in  the  liszt 
environment  that  would  normally  be  entered  by  a  declare  statement. 
The  arguments  to  liszt-declare  have  the  same  syntax  as  the  arguments 
to  declare.  However,  localf  declarations  are  not  remembered. 

Note  that  the  arguments  of  liszt- declare  are  not  evaluated. 
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(macroexpand  'g_expression)  [LISP  Function] 

FIXED  BUG:  FRANZ  iiuicroe.rpand  dkl  not  handle  vlambda's.  All  nlambda^s  in  lisp  and 
liszt  are  now  handled. 


(self  ...) 
FIXED  BUG: 


FIXED  BUG: 


[LISP  Macro] 

5e// cannot  handle  a  single  symbol  returned  by  expansion  of  a  macro  first 
argument  to  setf.  Such  expansions  should  be  handled  the  same  as  original 
input  arguments,  so  self  should  become  sctq  in  this  case. 

If  setf  cannot  find  a  macro  definition  for  an  expression  first  argument,  it 
gives  up.  It  should  try  apply  anyway  if  no  function  definition  exists  for  the 
function  symbol  of  the  first  argument,  so  that  the  function  may  become 
defined  by  the  undefined  function  error  handlers. 
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1.  GLOSSARY. 

‘‘display  daemon”  (SKETCH  Term] 

display  protocol”  [SKETCH  Term] 

USE:  A  SKETCH  display  daemon  is  a  program  that  runs  on  a  computer  with  display 
hardware,  and  makes  that  hardware  available  over  networks. 

The  SKETCH  display  protocol  is  the  language  used  to  communicate  with  a  display 
daemon  on  another  computer  (or  even  on  your  own  computer). 

STARTING  D.VE.MONS:  A  daemon  may  be  started  by  executing  the  following  command  in 

a  directory  containing  the  sdd  package  binaries— 

fravied  [—debug]  <port-number> 

<device>  <device-program  >  <device-argument  >  ... 

The  -debug  option  causes  a  trace  of  the  commands  received  and 
the  number  of  bytes  sent  and  received.  The  trace  is  written  to  the 
UNIX  standard  error  file. 

The  <port-number>  is  the  port  on  which  the  daemon  will  listen. 
Port  1201  is  typical.  See  a-display  in  the  SKETCH  Display  Pack¬ 
age  for  ways  to  set  the  <port-number>  to  which  user  of  the  dae¬ 
mon  tries  to  connect. 

The  <device>  is  the  name  of  the  device  being  supported,  also 
specified  by  a-display  in  the  SKETCH  Display  Package.  Typical 
values  are  cgoneO  and  fb  for  a  SUN3  computer. 

The  <device-program  >  designates  which  program  will  actually 
do  the  work  of  the  deamon.  This  is  a  binary  program  in  the  sdd 
package  directory.  The  most  useful  current  value  is  pixrecid- 
nocameradf  which  uses  the  SUN3  pixreci  facility  to  access  a  SUN3 
display  device,  and  which  does  not  support  any  camera.  This  pro¬ 
gram  takes  one  <device-argument>,  the  file  name  of  the 
hardware  display  device,  typically  either  /dev/cgoneO  or  /dev/fb. 

The  framed  program  can  support  multiple  devices  with  different 
<device>  identifiers.  To  do  so  multiple 
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<device>  <cievice-program  >  <device-argument>  ... 

sequences  are  included  in  the  framed  argument  list  and  separated 
by  slash  (/)  arguments.  E.g. 

framed  1201  cgoneO  pixrectd-nocamerad  /dev/cgoneO 
/  fb  pixrectd-nocamerad  /dev/fb 

However,  the  -debug  option  is  not  likely  to  work  well  if  two 
deamons  are  serving  two  different  devices  at  once. 

To  talk  to  a  display  daemon  you  must  open  a  connection  to  the  daemon. 
First  you  need  to  know  the  host  and  port  number  of  the  daemon.  The 
port  number  is  given  as  an  argument  to  the  daemon  when  it  is  started. 
The  following  code  is  typical  for  making  a  connection- 

refine  ushort  USHORT 
^include  <sys/types.h  > 

^undef  ushort 

^include  <sySy^socket.h> 

^include  < netinet/in.h > 

^include  <netdb.h> 


char  *  host; 
int  port 


int  s,  i; 

struct  sockaddr.in  sin; 
register  struct  hostent  *h; 


s  =  socket(AF JNET,  SOCIC-STREAM,  0); 
if  (s  <  0)  ...  notate  error  given  by  errno  ... 
h  =  gethostbyname(host); 
if  (h  ==  NULL)  ...  notate  error  ... 
sin.sinj'amily  =  h— >h_addrtype; 

bcopy(h— >h_addr,  (caddr_t)&sin.sin_addr,  h— >h_length); 
sin.sin_port  =  htons(port); 

i  =  connect(s,  &sin,  sizeof(sin)); 

if  (i  <  0)  ...  notate  error  given  by  errno  ... 

At  this  point  s  is  a  socket  descriptor  of  a  connection  into  which  data 
may  be  sent  by— 

i  =send  (s,  (caddr_t)data,  sizeof  data,  0)  <  0); 
if  (i  <  0)  ...  notate  error  given  by  errno  ... 

and  received  by  a  subroutine  such  as— 
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static  int 

receive  (s.  buffer,  length) 
int  s; 

register  char  *  buffer; 
register  int  length; 

{ 

register  int  c; 
errno  =  0; 

while  (length  >  0  &&  (c  =  recv  (s,  buffer,  length,  0))  !=  0)  { 
if  (c  <  0)  return  (c); 
buffer  -l-=  c; 
length  -=  c;  } 

return  (length  ==  0  ?  0  :  -1);  } 

PROTOCOL:  The  protocol  consists  of  messages.  Each  is  a  sequence  of  32  bit  integers  (in 
network  standard  format:  see  the  UNIX  subroutines  iitol  and  Iton  in 
byteorder  (3N)),  followed  by  zero  or  more  byte  strings.  The  integers  tell  the 
length  of  the  byte  strings  (directly  or  indirectly). 

There  are  two  kinds  of  messages;  requests  and  responses.  The  first  integer 
of  a  request  indicates  the  request  type;  currently  one  of— 

open  close  clear  map  camera  write  flush  nop. 

The  following  requests  have  a  response  message  whose  first  integer  is  the 
same  as  that  of  the  corresponding  request- 

open  close  flush. 

The  nop,  or  no-operation  message  consists  of  a  single  4-byte  integer  (the 
request  type)  that  is  ignored  when  sent  either  as  a  request  or  a  response. 
One  nop  must  be  sent  after  every  request  for  which  a  response  is  expected, 
before  the  response  is  read,  to  flush  the  request  across  to  the  daemon.  Simi¬ 
larly  the  daemon  sends  a  nop  after  every  response  before  reading  the  next 
request. 

Any  request  can  also  return  an  error  response  message.  This  will  be  read 
after  the  next  request  for  which  a  response  is  expected. 

REQUEST/RESPONSE  CODES:  The  following  are  the  current  values  of  the  request  and 

response  codes  (the  requests  and  responses  are  documented 
elsewhere)— 
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Name 

Value 

Meaning. 

FR_OPEN 

OxAAAAAAAl 

Open  display  device. 

FR_CLOSE 

0xAAAAAAA2 

Close  display  device. 

FRJERROR 

OxAAAAAAAS 

Error  message  response. 

FR_CLEAR 

0xAAAAAAA4 

Clear  all  pixels  to  a  single  value. 

FR_MAP 

OxAAAAAAAS 

Set  color  map. 

FR_CAMERA 

OxAAAAAAAS 

Set  camera  parameters. 

FR_WRITE 

OxAAAAAAA? 

Write  block  of  pixels. 

FR_FLUSH 

OxAAAAAAAS 

Flush  memory  to  display  proper. 

FR_NOP 

0xAAAAAAA9 

No  operation. 

ERROR  RECOVERY:  If  there  is  any  error  on  a  connection,  the  user  should  close  the  con¬ 
nection  (via  the  UNIX  close  (2)  routine,  not  FR^CLOSE^  and  reopen 
a  new  connection  to  the  display  device.  The  user  should  keep  a  copy 
of  the  device  memory  (map,  camera  parameters,  and  display  pixels), 
so  it  can  reinitialize  these  when  the  display  device  is  reopened  after 
an  error. 

FR_CAMERA 

[C  Macro] 

FR_CAMERA  camera_string_size  camera^tring  [SKETCH  Display  Daemon  Request] 
USE:  Stores  camera  parameters  in  the  camera. 

For  a  Matrix  camera,  these  parameters  are  represented  by  an  ASCII  character 
string,  camera_string,  of  camera^tring_size  bytes,  with  a  format  to  be  determined 
later  when  this  feature  is  implemented. 

The  camera  parameters  should  be  sent  after  FR^OPENwig  the  display  device  and 
before  using  the  camera. 

This  request  has  no  response  if  it  is  successful.  If  it  is  not  successful  an  error  mes¬ 
sage  is  returned  (which  is  normally  read  later  when  the  user  is  trying  to  read  the 
response  from  an  FRJ'LUSH). 
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FR.CLEAR  [C  Macro] 

FR_CLEAR  xorigin  yorigin  [SKETCH  Display  Daemon  Request] 

xsize  ysize  pixeLvalue 

USE:  Similar  to  FR^WRITE  except  that  all  pixels  in  the  subimage  are  set  to  the  same 
value.  This  value  is  passed  as  an  integer  in  network  standard  format.  If  pixels  are 
one  byte  long,  then  this  integer  is  in  the  range  from  0  through  255. 

This  request  has  no  response  if  it  is  successful.  If  it  is  not  successful  an  error  mes¬ 
sage  is  returned  (which  is  normally  read  later  when  the  user  is  trying  to  read  the 
response  from  an  FR^LVSH). 

FR^ERROR  [C  Macro] 

FRJJRROR  mcssage^size  message^tring  [SKETCH  Display  Daemon  Request] 

USE:  This  is  a  response  to  any  request  during  the  execution  of  which  the  display  daemon 
detects  an  error.  The  message_string  is  a  character  string  of  message^ize  bytes 
(without  a  NUL  byte  on  the  end).  The  message  string  should  be  formated  in  such 

a  w'ay  that  it  can  be  read  by  the  LISP  rcarf  function  and  converted  into  a  valid 

LISP  object,  which  becomes  an  error  message  printable  via  pretty-print. 

FRJ'LUSH  [C  Macro] 

FRJ'LUSH  delay _time  exposure_coiint  [SKETCH  Display  Daemon  Request] 

FR_FLUSH  [SKETCH  Display  Daemon  Response] 

USE:  The  image  and  color  maps  stored  in  the  display  daemon  are  written  to  the  display 
device  (this  may  or  may  not  have  been  previously  done).  After  this  is  done,  the 
state  of  the  display  device  is  not  changed  until  first  exposure_count  pictures  have 
been  taken  by  the  camera,  and  then  delay^time  milliseconds  have  elapsed.  During 
this  period  new  FR^WRITE,  FR^CLEAR^  and  FR^MAP  requests  may  be  pro¬ 
cessed  if  they  do  not  effect  the  display  device  state,  but  only  change  the  memory  of 
the  display  daemon. 

The  FR^LUSH  requests  sends  a  response  after  the  display  device  image  and  color 
map  are  written,  but  before  the  camera  exposures  have  been  taken  or  the  delay  has 
occurred.  To  get  a  response  after  the  exposures  and  delay,  send  a  second 
FRJ'LUSH  with  zero  exposure_count  and  zero  dclay_time,  or  send  an 
FR^CLOSE.  Neither  of  these  two  requests  will  respond  until  exposures  and  delays 
of  previous  requests  have  finished. 
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FR31AP  |C  Macro] 

FR31AP  xsize  ysize  map.type  map_st  riiig  [SKETCH  Display  Daemon  Request] 

USE:  Stores  a  color  map  in  the  display  device  daemon  (the  color  map  may  not  be  written 
to  the  display  hardware  until  the  next  FRJ'LUSH  request,  but  on  the  other  hand 
it  may  be  written  to  the  hardware  sooner). 

The  meaning  of  xsize  and  ysize,  and  the  format  of  map_j5tring,  can  be  display  dev¬ 
ice  specific.  However,  the  following  standard  is  recommended  where  applicable: 
xsize  =  3,  ysize  =  256,  with  map_string  consisting  of  3*256  bytes,  each  an  unsigned 
integer  representing  an  intensity  for  one  color.  The  first  three  bytes  are  the  red, 
green,  and  blue  intensities,  in  that  order,  for  image  pixels  of  value  0;  the  next  three 
bytes  are  for  pixels  of  value  1:  etc. 

The  display  device  stores  two  color  maps.  If  type  ==  0,  the  normal  color  map  is 
set,  whereas  if  type  ==  1,  the  camera  map  is  set.  The  later  is  used  temporarily 
only  while  the  camera  is  taking  a  picture  (see  FR_FLUSH). 

The  normal  map  should  be  sent  after  FR_OPE!^mg  the  display  device  and  before 
writing  any  image  via  FR^WRJTE  ov  FR_CLEAR. 

The  camera  map  should  be  sent  after  FR_OPEN'\ng  the  display  device  and  before 
using  the  camera. 

This  request  has  no  response  if  it  is  successful.  If  it  is  not  successful  an  error  mes¬ 
sage  is  returned  (which  is  normally  read  later  when  the  user  is  trying  to  read  the 
response  from  an  FR^FLUSH), 

FR_NOP  [C  Macro] 

FR_NOP  (SKETCH  Display  Daemon  Request] 

FR_NOP  [SKETCH  Display  Daemon  Response] 

USE:  If  this  is  received  as  either  a  request  or  a  response,  it  is  ignored. 

Some  network  implementations  seem  to  be  unable  to  deliver  all  the  bytes  of  a  mes¬ 
sage  to  the  receiver  until  another  message  has  been  sent.  For  the  sake  of  these,  an 
should  be  sent  after  each  request  for  which  a  response  is  expected.  Simi¬ 
larly  the  daemon  may  send  an  F7?_NOP  after  each  response. 
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FR^OPEN  [C  Macro] 

FR^OPEN  user_id_size  device^size  [SKETCH  Display  Daemon  Request] 

processor^size  monitor_size  camera^size 
uscr_id_string  device^string 
processor^string  monitor_string  camera^tring 
FR_OPEN  [SKETCH  Display  Daemon  Response] 


FR_CLOSE  [C  Macro] 

FR_ CLOSE  [SKETCH  Display  Daemon  Request] 

FR_CLOSE  (SKETCH  Display  Daemon  Response] 

USE:  The  open  display  daemon  request  opens  a  specific  hardware  display,  making  it 
usable  until  it  is  closed.  The  request  consists  of  a  number  of  character  strings,  the 
size  in  bytes  of  each  being  given  with  the  request  integers.  The  userjd^tring 
identifies  the  user  so  that  other  users  can  find  him  when  they  find  that  the  display 
is  busy.  The  device^string  specifies  which  display  device  is  to  be  used  (one  daemon 
may  handle  many  displays  for  many  different  users  on  one  computer). 
Device^string  must  match  a  device  argument  given  to  the  display  daemon  when  it 
is  started  (see  display  daemon). 


I'he  processor_string  refers  to  the  display  processor  type,  the  monitor_;strmg  to  the 
display  monitor  type,  and  the  camera_string  to  the  display  camera  type.  See  a- 
disptay  in  the  SKETCH  Display  Package.  Currently  the  daemon  does  not  use 
these. 


The  close  request  terminates  use  of  a  particular  piece  of  display  hardware,  and 
releases  all  resources.  It  should  be  followed  by  closing  the  connection  (and  not  by 
trying  to  open  another  display  device). 

If  the  daemon  successfully  processes  the  open  or  close  request,  it  returns  an  open  or 
close  response,  consisting  of  one  4-byte  integer  with  the  same  type  code  as  the 
request  (F REOPEN  or  FR^CLOSE^.  Otherwise  the  daemon  returns  an  error  mes¬ 
sage  {FR^RROR). 

If  there  is  any  error  on  a  connection,  the  user  should  close  the  connection  (via  the 
UNIX  close  (2)  routine,  not  FR^CLOSE^  and  reopen  a  new  connection  to  the 
display  device.  The  user  should  keep  a  copy  of  the  device  memory  (map,  camera 
parameters,  and  display  pixels),  so  it  can  reinitialize  these  when  the  display  device 
is  reopened  after  an  error. 
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FR^WRITE  [C  Macro] 

FR^WRITE  xorigin  yorigin  [SKETCH  Display  Daemon  Request] 

xsize  ysize  psize  pixeLstring 

USE:  Stores  a  rectangular  subimage  within  the  display  device  image.  The  coordinates  of 
the  upper  left  pixel  of  the  subimage  are  xorigin  and  yorigin.  The  0,0  pixel  of  the 
display  device  is  its  upper  left  corner,  the  x  coordinate  is  horizontal,  and  the  y 
coordinate  is  vertical  (increasing  from  top  to  bottom).  The  size  of  the  subimage  in 
pixels  is  given  by  xsize  and  ysize.  The  number  of  bytes'per  pixel  is  given  by  psize 
(which  is  normally  equal  to  1).  The  pixels  are  stored  in  pixeLstring.  Each  pixel  is 
a  contiguous  string  of  bytes;  and  each  horizontal  row  is  a  contiguous  string  of  pix¬ 
els.  Therefore  pixel_string  is 

xsize  *  ysize  *  psize 

bytes  long. 

For  one  byte  pixels,  the  pixels  are  interpreted  as  a  number  from  0  through  255  that 
indexes  the  color  map  (see  FR^iAP).  It  is  suggested  that  the  formats  assumed  by 
the  SUN  pixrect  package  be  used  to  guide  pixel  format  standards  in  other  cases. 

This  request  has  no  response  if  it  is  successful.  If  it  is  not  successful  an  error  mes¬ 
sage  is  returned  (which  is  normally  read  later  when  the  user  is  trying  to  read  the 
response  from  an  FR^FLUSH). 
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1. 

FR.ANZ  EXTENSIONS. 

sfe_demo 

o 

ATO.MS. 

sat_deino 

3 

OBJECTS. 

sob-cdemo,  sob~hdemo,  sob_vdemo 

A 

CAT.AJ.OGS. 

sea— demo 

5. 

ARRAYS. 

sar_demo,  sar-gcdenio 

6. 

BASIC  ARITHMETIC. 

sba— demo 

7. 

BIT  GRAPHICS 

sbg_demo 

8. 

ANALYTIC  GEOMETRY. 

sag-demo 

9. 

DISPLAY. 

sdi-demo,  sdi_cdemo 

10. 

HISTOGRAMS. 

shi-demo 

11. 

EDGES. 

sed-demo 

12. 

LINEAR  FIT. 

slf-demo 

13. 

TEXTURE. 

stx-demo 
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